# evermind-ai/everos architecture

> Architecture diagram of the GitHub repository evermind-ai/everos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evermind-ai/everos
- Repository: https://github.com/evermind-ai/everos

## Overview

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: [`src/everos/entrypoints/api/app.py`](https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/api/app.py) (HTTP API), [`src/everos/memory/extract/pipeline/base.py`](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/extract/pipeline/base.py) (Ingest pipeline), [`src/everos/entrypoints/api/lifespans/llm.py`](https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/api/lifespans/llm.py) (Lifespans), [`src/everos/memory/search/manager.py`](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/search/manager.py) (Search manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry points"]
  node_cli_main["CLI<br/>entrypoint<br/>[main.py]"]
  node_api_app["HTTP API<br/>server entrypoint<br/>[app.py]"]
  node_tui_demo["TUI demo<br/>demo entrypoint<br/>[app.py]"]
end

subgraph group_services["Services"]
  node_memorize_service["Memorize<br/>service orchestrator<br/>[memorize.py]"]
  node_search_service["Search<br/>service orchestrator<br/>[search.py]"]
  node_knowledge_service["Knowledge<br/>service orchestrator<br/>[knowledge.py]"]
  node_get_service["Get<br/>service orchestrator<br/>[get.py]"]
end

subgraph group_memory["Memory domain"]
  node_ingest_pipeline["Ingest pipeline<br/>memory pipeline<br/>[base.py]"]
  node_parser_stage["Parse + enrich<br/>memory stage<br/>[enrich.py]"]
  node_search_manager["Search manager<br/>memory search<br/>[manager.py]"]
  node_agentic_search["Agentic search<br/>memory search<br/>[agentic.py]"]
  node_reflection_orch["Reflection<br/>memory workflow<br/>[orchestrator.py]"]
  node_cascade_orch["Cascade<br/>memory workflow<br/>[orchestrator.py]"]
end

subgraph group_persistence["Persistence"]
  node_markdown_store["Markdown store<br/>canonical persistence<br/>[writer.py]"]
  node_sqlite_store[("SQLite store<br/>operational persistence<br/>[repository.py]")]
  node_lancedb_store[("LanceDB store<br/>retrieval index<br/>[repository.py]")]
end

subgraph group_components["Model components"]
  node_llm_client["LLM client<br/>model provider<br/>[factory.py]"]
  node_embed_client["Embedding client<br/>model provider<br/>[factory.py]"]
  node_rerank_client["Rerank client<br/>model provider<br/>[factory.py]"]
  node_tokenizer["Tokenizer<br/>language helper<br/>[factory.py]"]
end

subgraph group_infra["Infrastructure"]
  node_api_lifespans["Lifespans<br/>composition root<br/>[llm.py]"]
  node_middleware["Middleware<br/>[prometheus.py]"]
  node_ome_engine["OME engine<br/>background runtime<br/>[engine.py]"]
  node_persistence_adapters["Infra repos<br/>storage adapters<br/>[lancedb_manager.py]"]
end

node_cli_main -->|"invoke"| node_memorize_service
node_cli_main -->|"run cascade"| node_cascade_orch
node_api_app -->|"compose"| node_api_lifespans
node_api_app -->|"wrap"| node_middleware
node_api_app -->|"route"| node_memorize_service
node_api_app -->|"route"| node_search_service
node_api_app -->|"route"| node_knowledge_service
node_api_app -->|"route"| node_get_service
node_tui_demo -->|"read"| node_get_service
node_memorize_service -->|"build"| node_ingest_pipeline
node_ingest_pipeline -->|"transform"| node_parser_stage
node_ingest_pipeline -->|"persist"| node_markdown_store
node_ingest_pipeline -->|"state"| node_sqlite_store
node_ingest_pipeline -->|"index"| node_lancedb_store
node_search_service -->|"delegate"| node_search_manager
node_search_manager -->|"escalate"| node_agentic_search
node_search_manager -->|"retrieve"| node_lancedb_store
node_search_manager -->|"analyze"| node_tokenizer
node_search_manager -->|"rank"| node_rerank_client
node_agentic_search -->|"reason"| node_llm_client
node_knowledge_service -->|"source"| node_markdown_store
node_knowledge_service -->|"search"| node_lancedb_store
node_get_service -->|"lookup"| node_sqlite_store
node_reflection_orch -->|"extract"| node_llm_client
node_cascade_orch -->|"drive"| node_ome_engine
node_ome_engine -->|"track"| node_sqlite_store
node_ome_engine -->|"update"| node_markdown_store
node_ome_engine -->|"execute"| node_llm_client
node_api_lifespans -->|"init"| node_llm_client
node_api_lifespans -->|"init"| node_sqlite_store
node_api_lifespans -->|"init"| node_lancedb_store
node_api_lifespans -->|"init"| node_cascade_orch
node_api_lifespans -->|"init"| node_ome_engine
node_persistence_adapters -->|"implement"| node_markdown_store
node_persistence_adapters -->|"implement"| node_sqlite_store
node_persistence_adapters -->|"implement"| node_lancedb_store
node_ingest_pipeline -->|"embed"| node_embed_client

click node_cli_main "https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/cli/main.py"
click node_api_app "https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/api/app.py"
click node_tui_demo "https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/tui/demo/app.py"
click node_memorize_service "https://github.com/evermind-ai/everos/blob/main/src/everos/service/memorize.py"
click node_search_service "https://github.com/evermind-ai/everos/blob/main/src/everos/service/search.py"
click node_knowledge_service "https://github.com/evermind-ai/everos/blob/main/src/everos/service/knowledge.py"
click node_get_service "https://github.com/evermind-ai/everos/blob/main/src/everos/service/get.py"
click node_ingest_pipeline "https://github.com/evermind-ai/everos/blob/main/src/everos/memory/extract/pipeline/base.py"
click node_parser_stage "https://github.com/evermind-ai/everos/blob/main/src/everos/memory/extract/parser/enrich.py"
click node_search_manager "https://github.com/evermind-ai/everos/blob/main/src/everos/memory/search/manager.py"
click node_agentic_search "https://github.com/evermind-ai/everos/blob/main/src/everos/memory/search/agentic.py"
click node_reflection_orch "https://github.com/evermind-ai/everos/blob/main/src/everos/memory/reflection/orchestrator.py"
click node_cascade_orch "https://github.com/evermind-ai/everos/blob/main/src/everos/memory/cascade/orchestrator.py"
click node_markdown_store "https://github.com/evermind-ai/everos/blob/main/src/everos/core/persistence/markdown/writer.py"
click node_sqlite_store "https://github.com/evermind-ai/everos/blob/main/src/everos/core/persistence/sqlite/repository.py"
click node_lancedb_store "https://github.com/evermind-ai/everos/blob/main/src/everos/core/persistence/lancedb/repository.py"
click node_llm_client "https://github.com/evermind-ai/everos/blob/main/src/everos/component/llm/factory.py"
click node_embed_client "https://github.com/evermind-ai/everos/blob/main/src/everos/component/embedding/factory.py"
click node_rerank_client "https://github.com/evermind-ai/everos/blob/main/src/everos/component/rerank/factory.py"
click node_tokenizer "https://github.com/evermind-ai/everos/blob/main/src/everos/component/tokenizer/factory.py"
click node_api_lifespans "https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/api/lifespans/llm.py"
click node_middleware "https://github.com/evermind-ai/everos/blob/main/src/everos/core/middleware/prometheus.py"
click node_ome_engine "https://github.com/evermind-ai/everos/blob/main/src/everos/infra/ome/engine.py"
click node_persistence_adapters "https://github.com/evermind-ai/everos/blob/main/src/everos/infra/persistence/lancedb/lancedb_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_main,node_api_app,node_tui_demo toneBlue
class node_memorize_service,node_search_service,node_knowledge_service,node_get_service toneAmber
class node_ingest_pipeline,node_parser_stage,node_search_manager,node_agentic_search,node_reflection_orch,node_cascade_orch toneMint
class node_markdown_store,node_sqlite_store,node_lancedb_store toneRose
class node_llm_client,node_embed_client,node_rerank_client,node_tokenizer toneIndigo
class node_api_lifespans,node_middleware,node_ome_engine,node_persistence_adapters toneTeal
```

## Components

### Entry points

User-facing CLI, API, and TUI surfaces

- [CLI](https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/cli/main.py): entrypoint · Command-line interface for init, server, cascade, config, and demo flows · `src/everos/entrypoints/cli/main.py`
- [HTTP API](https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/api/app.py): server entrypoint · FastAPI application composed from routes, middleware, and lifespans · `src/everos/entrypoints/api/app.py`
- [TUI demo](https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/tui/demo/app.py): demo entrypoint · Standalone local demo visualizer · `src/everos/entrypoints/tui/demo/app.py`

### Services

Application orchestration for memory and knowledge use cases

- [Memorize](https://github.com/evermind-ai/everos/blob/main/src/everos/service/memorize.py): service orchestrator · Coordinates ingestion and durable writes for memory use cases · `src/everos/service/memorize.py`
- [Search](https://github.com/evermind-ai/everos/blob/main/src/everos/service/search.py): service orchestrator · Coordinates memory recall and search requests · `src/everos/service/search.py`
- [Knowledge](https://github.com/evermind-ai/everos/blob/main/src/everos/service/knowledge.py): service orchestrator · CRUD and search for source-backed knowledge artifacts · `src/everos/service/knowledge.py`
- [Get](https://github.com/evermind-ai/everos/blob/main/src/everos/service/get.py): service orchestrator · Retrieval of stored memory and knowledge items · `src/everos/service/get.py`

### Memory domain

Ingest, search, recall, reflection, and cascade workflows

- [Ingest pipeline](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/extract/pipeline/base.py): memory pipeline · Parses, enriches, maps, and persists incoming content · `src/everos/memory/extract/pipeline/base.py`
- [Parse + enrich](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/extract/parser/enrich.py): memory stage · Availability checks, parser enrichment, and mapping into memory objects · `src/everos/memory/extract/parser/enrich.py`
- [Search manager](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/search/manager.py): memory search · Hybrid retrieval orchestration across adapters, filters, shapers, and recall handlers · `src/everos/memory/search/manager.py`
- [Agentic search](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/search/agentic.py): memory search · LLM-assisted multi-step recall path · `src/everos/memory/search/agentic.py`
- [Reflection](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/reflection/orchestrator.py): memory workflow · Deferred reflection workflow over extracted episodes and memory artifacts · `src/everos/memory/reflection/orchestrator.py`
- [Cascade](https://github.com/evermind-ai/everos/blob/main/src/everos/memory/cascade/orchestrator.py): memory workflow · 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](https://github.com/evermind-ai/everos/blob/main/src/everos/core/persistence/markdown/writer.py): canonical persistence · File-backed source of truth with frontmatter, readers, and writers · `src/everos/core/persistence/markdown/writer.py`
- [SQLite store](https://github.com/evermind-ai/everos/blob/main/src/everos/core/persistence/sqlite/repository.py): operational persistence · Transactional operational state and session tables · `src/everos/core/persistence/sqlite/repository.py`
- [LanceDB store](https://github.com/evermind-ai/everos/blob/main/src/everos/core/persistence/lancedb/repository.py): retrieval index · 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](https://github.com/evermind-ai/everos/blob/main/src/everos/component/llm/factory.py): model provider · Pluggable text generation provider abstraction · `src/everos/component/llm/factory.py`
- [Embedding client](https://github.com/evermind-ai/everos/blob/main/src/everos/component/embedding/factory.py): model provider · Pluggable embedding provider abstraction · `src/everos/component/embedding/factory.py`
- [Rerank client](https://github.com/evermind-ai/everos/blob/main/src/everos/component/rerank/factory.py): model provider · Pluggable reranking provider abstraction · `src/everos/component/rerank/factory.py`
- [Tokenizer](https://github.com/evermind-ai/everos/blob/main/src/everos/component/tokenizer/factory.py): language helper · Tokenization backend used by search and text processing · `src/everos/component/tokenizer/factory.py`

### Infrastructure

Concrete persistence adapters and background orchestration

- [Lifespans](https://github.com/evermind-ai/everos/blob/main/src/everos/entrypoints/api/lifespans/llm.py): composition root · Wires model clients, storage engines, and background subsystems at startup · `src/everos/entrypoints/api/lifespans/llm.py`
- [Middleware](https://github.com/evermind-ai/everos/blob/main/src/everos/core/middleware/prometheus.py): api middleware · CORS, profiling, and Prometheus instrumentation · `src/everos/core/middleware/prometheus.py`
- [OME engine](https://github.com/evermind-ai/everos/blob/main/src/everos/infra/ome/engine.py): background runtime · Background dispatch engine with scanner, watcher, worker, and recovery · `src/everos/infra/ome/engine.py`
- [Infra repos](https://github.com/evermind-ai/everos/blob/main/src/everos/infra/persistence/lancedb/lancedb_manager.py): storage adapters · Concrete markdown, SQLite, and LanceDB repositories for memory kinds · `src/everos/infra/persistence/lancedb/lancedb_manager.py`

## Connections

- 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
