How evermind-ai/everos works
1. What this repo is
EverOS is a Python 3.12+ local-first memory runtime for agents and users. The core idea is a three-layer storage model: human-readable Markdown as the source of truth, SQLite for operational state, and LanceDB for retrieval/search indexes.
2. Top-level runtime boundaries
The repository is organized into:
- src/everos/component: pluggable model/provider clients and low-level helpers
- src/everos/core: shared runtime concerns like persistence primitives, middleware, logging, metrics, lifespans
- src/everos/memory: the domain layer for ingest, extraction, search, recall, reflection, and cascade workflows
- src/everos/service: application services that coordinate memory and knowledge use cases
- src/everos/entrypoints: CLI, HTTP API, and TUI entrypoints
- src/everos/infra: concrete persistence and orchestration infrastructure
3. Primary data flow for memory ingestion
The main write path starts at the API/CLI and enters the service layer, then the memory pipelines. Incoming chat/messages or multimodal content are parsed, enriched, and mapped into memory objects, then persisted as Markdown and indexed through SQLite/LanceDB-backed repositories. The README’s “add -> flush -> search” flow reflects this separation: synchronous durable write first, then background index catch-up for retrieval.
4. Memory domain model
The system explicitly separates user and agent memory surfaces. Under memory/ and infra/persistence/ you can see specialized entities such as episodes, atomic facts, profiles, skills, cases, foresights, knowledge topics, and documents. This is important for diagrams: the architecture is not one generic chat-history store, but multiple memory kinds with distinct extraction and retrieval paths.
5. Cascade subsystem for self-evolving memory
memory/cascade and infra/ome together implement the background “cascade” mechanics: scanning, watching, dispatching, worker execution, reconciliation, and idle/crash recovery. This is the offline evolution layer that merges/updates memory artifacts after ingestion, rather than only supporting retrieval. It is a major boundary between real-time capture and deferred consolidation.
6. Search and recall path
Search is implemented as a dedicated subsystem under memory/search, with adapters, filters, ranking, shaping, and recall handlers per memory kind. Retrieval is hybrid: it uses structured filters and hierarchy-aware shaping on top of the indexed stores, rather than pure vector search. There is also an “agentic” search path, which suggests an LLM-assisted or multi-step query strategy for more complex recall.
7. Knowledge wiki subsystem
Knowledge is treated separately from conversational memory. service/knowledge.py, entrypoints/api/routes/knowledge.py, and the Markdown/LanceDB repositories for knowledge topics/documents support CRUD plus topic search. The README calls this an editable, source-backed knowledge wiki, which means knowledge pages are first-class artifacts, not just search results.
8. Persistence architecture
There are two concrete persistence backends:
- core/persistence/markdown and infra/persistence/markdown: canonical markdown file readers/writers and frontmatter handling
- core/persistence/sqlite and infra/persistence/sqlite: transactional operational state, session/cluster/status tables
- core/persistence/lancedb and infra/persistence/lancedb: indexed retrieval storage
The presence of memory_root.py and markdown writers/readers indicates the file system is the durable source of truth, while SQLite/LanceDB are derived stores.
9. Model/provider abstraction
component/llm, component/embedding, component/rerank, and component/tokenizer define provider protocols and factories. Concrete providers include OpenAI-compatible LLMs, embedding, rerank, vLLM, DashScope, DeepInfra, and jieba tokenization. This abstraction layer is central because the runtime expects pluggable model endpoints rather than one fixed vendor.
10. Entry points and deployment surface
The repo exposes three user-facing surfaces:
- entrypoints/cli: everos demo, init, server, cascade, config commands
- entrypoints/api: the HTTP server with routes for health, add/memorize, get, search, knowledge, metrics, and OME-related operations
- entrypoints/tui: a standalone demo visualizer
The demo TUI is intentionally local and hardcoded; it does not exercise the server stack unless run in --live mode.
11. HTTP API and server composition
The API app is assembled from route modules and lifespan modules. Lifespans wire up model clients and storage engines at startup (llm, sqlite, lancedb, cascade, ome), while middleware adds CORS, profiling, and Prometheus metrics. This makes the server a composition root that binds infrastructure into the service layer.
12. Observability and operational support
core/observability provides logging, metrics, and tracing primitives; core/middleware/prometheus.py and entrypoints/api/routes/metrics.py expose operational telemetry. There is also explicit support for health checks, profile middleware, and metrics lifespan, which means the system is designed to be run as a long-lived service, not just a library.
13. Optional multimodal ingestion
The README and memory ingest code show that /memory/add can accept multimodal content when the optional extra is installed. Parsing uses everalgo-parser and may invoke LibreOffice headlessly for Office documents. That makes the ingestion pipeline include an external OS-level dependency and a parser boundary before the LLM/multimodal provider boundary.
14. Testing and repo-level validation
The repository is heavily tested across unit, integration, and end-to-end layers, with fixtures for chat sessions, agent trajectories, and search seeds. There are also many repo-check scripts and GitHub Actions workflows, so the project treats consistency of docs, datetime handling, commit hygiene, and API/docs alignment as part of the architecture.
15. How to draw the main diagram
A good architecture diagram should show:
- clients hitting CLI/API/TUI
- services orchestrating memory and knowledge use cases
- ingest pipelines producing Markdown source files plus SQLite/LanceDB indexes
- background cascade workers reconciling and evolving memory artifacts
- search/recall reading from indexed stores with model-assisted ranking
- external model providers supplying LLM, embedding, rerank, and multimodal capabilities
- observability and middleware wrapping the API runtime
Main entry points: app.py HTTP API · base.py Ingest pipeline · llm.py Lifespans · manager.py Search manager
Components 24
Entry points
User-facing CLI, API, and TUI surfaces
- CLI · Command-line interface for init, server, cascade, config, and demo flows
src/everos/entrypoints/cli/main.py - HTTP API · FastAPI application composed from routes, middleware, and lifespans
src/everos/entrypoints/api/app.py - TUI demo · Standalone local demo visualizer
src/everos/entrypoints/tui/demo/app.py
Services
Application orchestration for memory and knowledge use cases
- Memorize · Coordinates ingestion and durable writes for memory use cases
src/everos/service/memorize.py - Search · Coordinates memory recall and search requests
src/everos/service/search.py - Knowledge · CRUD and search for source-backed knowledge artifacts
src/everos/service/knowledge.py - Get · Retrieval of stored memory and knowledge items
src/everos/service/get.py
Memory domain
Ingest, search, recall, reflection, and cascade workflows
- Ingest pipeline · Parses, enriches, maps, and persists incoming content
src/everos/memory/extract/pipeline/base.py - Parse + enrich · Availability checks, parser enrichment, and mapping into memory objects
src/everos/memory/extract/parser/enrich.py - Search manager · Hybrid retrieval orchestration across adapters, filters, shapers, and recall handlers
src/everos/memory/search/manager.py - Agentic search · LLM-assisted multi-step recall path
src/everos/memory/search/agentic.py - Reflection · Deferred reflection workflow over extracted episodes and memory artifacts
src/everos/memory/reflection/orchestrator.py - Cascade · Background scanning, dispatch, reconciliation, and recovery for evolving memory
src/everos/memory/cascade/orchestrator.py
Persistence
Canonical markdown plus operational SQLite and retrieval LanceDB stores
- Markdown store · File-backed source of truth with frontmatter, readers, and writers
src/everos/core/persistence/markdown/writer.py - SQLite store · Transactional operational state and session tables
src/everos/core/persistence/sqlite/repository.py - LanceDB store · Indexed search and retrieval repository layer
src/everos/core/persistence/lancedb/repository.py
Model components
Pluggable provider clients and low-level runtime helpers
- LLM client · Pluggable text generation provider abstraction
src/everos/component/llm/factory.py - Embedding client · Pluggable embedding provider abstraction
src/everos/component/embedding/factory.py - Rerank client · Pluggable reranking provider abstraction
src/everos/component/rerank/factory.py - Tokenizer · Tokenization backend used by search and text processing
src/everos/component/tokenizer/factory.py
Infrastructure
Concrete persistence adapters and background orchestration
- Lifespans · Wires model clients, storage engines, and background subsystems at startup
src/everos/entrypoints/api/lifespans/llm.py - Middleware · CORS, profiling, and Prometheus instrumentation
src/everos/core/middleware/prometheus.py - OME engine · Background dispatch engine with scanner, watcher, worker, and recovery
src/everos/infra/ome/engine.py - Infra repos · Concrete markdown, SQLite, and LanceDB repositories for memory kinds
src/everos/infra/persistence/lancedb/lancedb_manager.py
Connections 37
- CLI → Memorize: invoke · CLI commands trigger ingestion and cascade operations
- CLI → Cascade: run cascade · CLI exposes background cascade control
- HTTP API → Lifespans: compose · API startup wires runtime dependencies
- HTTP API → Middleware: wrap · API requests pass through shared middleware
- HTTP API → Memorize: route · Memorize endpoints delegate to service orchestration
- HTTP API → Search: route · Search endpoints delegate to search orchestration
- HTTP API → Knowledge: route · Knowledge routes expose knowledge CRUD and search
- HTTP API → Get: route · Get endpoints fetch stored memory items
- TUI demo → Get: read · Demo UI can query stored items in live mode
- Memorize → Ingest pipeline: build · Service hands content to memory ingestion pipeline
- Ingest pipeline → Parse + enrich: transform · Pipeline parses, enriches, and maps incoming content
- Ingest pipeline → Markdown store: persist · Durable source-of-truth write happens to markdown first
- Ingest pipeline → SQLite store: state · Operational state is tracked in SQLite
- Ingest pipeline → LanceDB store: index · Derived retrieval indexes are updated for search catch-up
- Search → Search manager: delegate · Search service forwards queries to domain search manager
- Search manager → Agentic search: escalate · Complex recall can switch to agentic search
- Search manager → LanceDB store: retrieve · Hybrid recall reads from indexed retrieval storage
- Search manager → Tokenizer: analyze · Tokenization supports query and text handling
- Search manager → Rerank client: rank · Ranking can use external rerank providers
- Agentic search → LLM client: reason · Agentic recall uses an LLM for multi-step querying
- Knowledge → Markdown store: source · Knowledge artifacts remain editable Markdown sources
- Knowledge → LanceDB store: search · Knowledge search uses retrieval indexes
- Get → SQLite store: lookup · Operational metadata and status are read from SQLite
- Reflection → LLM client: extract · Reflection uses model assistance for summarization and extraction
- Cascade → OME engine: drive · Cascade workflow is implemented on top of the OME runtime
- OME engine → SQLite store: track · OME stores run state and reconciliation records in SQLite
- OME engine → Markdown store: update · Background handlers can reconcile markdown artifacts
- OME engine → LLM client: execute · Some handlers invoke model-backed work
- Lifespans → LLM client: init · Startup constructs provider clients
- Lifespans → SQLite store: init · Startup constructs SQLite-backed repositories
- Lifespans → LanceDB store: init · Startup constructs LanceDB-backed repositories
- Lifespans → Cascade: init · API lifespan wires cascade background subsystems
- Lifespans → OME engine: init · OME runtime is bootstrapped during server startup
- Infra repos → Markdown store: implement · Infrastructure provides concrete markdown repositories and writers
- Infra repos → SQLite store: implement · Infrastructure provides concrete SQLite repositories
- Infra repos → LanceDB store: implement · Infrastructure provides concrete LanceDB repositories
- Ingest pipeline → Embedding client: embed · Ingestion may generate embeddings for retrieval