# animalab/anima architecture

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

- Interactive diagram: https://gitdiagram.com/animalab/anima
- Repository: https://github.com/animalab/anima

## Overview

Anima is a local-first memory engine for assistants. Its main workflow accepts memories through the REST API, persists them in SQLite, and retrieves them through hybrid search; optional ask/chat flows use an LLM to turn retrieved context into answers. Separate branches provide background reflection and consolidation, MCP access, and a web console for search, chat, and memory inspection. The excerpts show API routing, selected handler-to-store calls, and some UI/API behavior; several subsystem connections are documented in the README but their implementation was not sampled.

Main entry points: [`crates/anima-server/src/handlers.rs`](https://github.com/animalab/anima/blob/main/crates/anima-server/src/handlers.rs) (Memory and chat handlers), [`crates/anima-server/src/main.rs`](https://github.com/animalab/anima/blob/main/crates/anima-server/src/main.rs) (HTTP server), [`crates/anima-db/src/store.rs`](https://github.com/animalab/anima/blob/main/crates/anima-db/src/store.rs) (Memory store), [`crates/anima-consolidate/src/consolidator.rs`](https://github.com/animalab/anima/blob/main/crates/anima-consolidate/src/consolidator.rs) (Memory consolidation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_server["HTTP server<br/>[main.rs]"]
  node_routing["API routing<br/>[app.rs]"]
  node_handlers["Memory and chat handlers<br/>[handlers.rs]"]
  node_config["Provider configuration<br/>[config.rs]"]
end

subgraph group_memory["Memory lifecycle"]
  node_processor["Background processor<br/>[processor.rs]"]
  node_consolidator["Memory consolidation<br/>[consolidator.rs]"]
  node_memory_model["Memory model<br/>[memory.rs]"]
  node_namespace["Namespace isolation<br/>[namespace.rs]"]
end

subgraph group_retrieval["Retrieval and models"]
  node_search["Hybrid search<br/>[search.rs]"]
  node_temporal["Temporal ranking<br/>[temporal.rs]"]
  node_embeddings["Embedding providers<br/>[model.rs]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.rs]"]
end

subgraph group_storage["Persistence"]
  node_store[("Memory store<br/>[store.rs]")]
  node_pool[("SQLite pool and schema<br/>[pool.rs]")]
  node_vectors[("Vector indexes<br/>[vector.rs]")]
  node_fts[("Keyword index<br/>[fts.rs]")]
end

subgraph group_surfaces["Integration surfaces"]
  node_web["Web console<br/>[App.tsx]"]
  node_web_api["Web API client<br/>[client.ts]"]
  node_mcp["MCP bridge<br/>[index.ts]"]
end

node_user(("Assistant or user"))
node_llm["LLM provider"]

node_user -->|"uses"| node_web
node_user -->|"uses"| node_mcp
node_user -->|"calls REST API"| node_server
node_server -->|"starts"| node_routing
node_routing -->|"routes requests"| node_handlers
node_web -->|"uses"| node_web_api
node_web_api -->|"sends REST requests"| node_server
node_mcp -->|"integrates via REST"| node_server
node_server -->|"loads settings"| node_config
node_handlers -->|"reads and writes memories"| node_store
node_store -->|"uses SQLite pool"| node_pool
node_pool -->|"initializes vector tables"| node_vectors
node_store -->|"uses keyword index"| node_fts
node_handlers -.->|"performs retrieval"| node_search
node_search -->|"uses temporal ranking"| node_temporal
node_handlers -->|"reranks candidates"| node_reranker
node_handlers -.->|"requests embeddings"| node_embeddings
node_processor -.->|"runs consolidation"| node_consolidator
node_handlers -.->|"queues processing"| node_processor
node_handlers -.->|"enforces namespace scope"| node_namespace
node_config -.->|"configures provider"| node_llm
node_consolidator -->|"requests completions"| node_llm
node_llm -->|"returns completions"| node_consolidator

click node_server "https://github.com/animalab/anima/blob/main/crates/anima-server/src/main.rs"
click node_routing "https://github.com/animalab/anima/blob/main/crates/anima-server/src/app.rs"
click node_handlers "https://github.com/animalab/anima/blob/main/crates/anima-server/src/handlers.rs"
click node_config "https://github.com/animalab/anima/blob/main/crates/anima-server/src/config.rs"
click node_processor "https://github.com/animalab/anima/blob/main/crates/anima-server/src/processor.rs"
click node_consolidator "https://github.com/animalab/anima/blob/main/crates/anima-consolidate/src/consolidator.rs"
click node_memory_model "https://github.com/animalab/anima/blob/main/crates/anima-core/src/memory.rs"
click node_namespace "https://github.com/animalab/anima/blob/main/crates/anima-core/src/namespace.rs"
click node_search "https://github.com/animalab/anima/blob/main/crates/anima-core/src/search.rs"
click node_temporal "https://github.com/animalab/anima/blob/main/crates/anima-core/src/temporal.rs"
click node_embeddings "https://github.com/animalab/anima/blob/main/crates/anima-embed/src/model.rs"
click node_reranker "https://github.com/animalab/anima/blob/main/crates/anima-embed/src/reranker.rs"
click node_store "https://github.com/animalab/anima/blob/main/crates/anima-db/src/store.rs"
click node_pool "https://github.com/animalab/anima/blob/main/crates/anima-db/src/pool.rs"
click node_vectors "https://github.com/animalab/anima/blob/main/crates/anima-db/src/vector.rs"
click node_fts "https://github.com/animalab/anima/blob/main/crates/anima-db/src/fts.rs"
click node_web "https://github.com/animalab/anima/blob/main/web/src/App.tsx"
click node_web_api "https://github.com/animalab/anima/blob/main/web/src/api/client.ts"
click node_mcp "https://github.com/animalab/anima/blob/main/mcp/src/index.ts"

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_server,node_routing,node_handlers,node_config,node_user toneBlue
class node_processor,node_consolidator,node_memory_model,node_namespace toneAmber
class node_search,node_temporal,node_embeddings,node_reranker toneMint
class node_store,node_pool,node_vectors,node_fts toneRose
class node_web,node_web_api,node_mcp,node_llm toneIndigo
```

## Components

### API runtime

- [HTTP server](https://github.com/animalab/anima/blob/main/crates/anima-server/src/main.rs): `crates/anima-server/src/main.rs`
- [API routing](https://github.com/animalab/anima/blob/main/crates/anima-server/src/app.rs): `crates/anima-server/src/app.rs`
- [Memory and chat handlers](https://github.com/animalab/anima/blob/main/crates/anima-server/src/handlers.rs): `crates/anima-server/src/handlers.rs`
- [Provider configuration](https://github.com/animalab/anima/blob/main/crates/anima-server/src/config.rs): `crates/anima-server/src/config.rs`

### Memory lifecycle

- [Background processor](https://github.com/animalab/anima/blob/main/crates/anima-server/src/processor.rs): `crates/anima-server/src/processor.rs`
- [Memory consolidation](https://github.com/animalab/anima/blob/main/crates/anima-consolidate/src/consolidator.rs): `crates/anima-consolidate/src/consolidator.rs`
- [Memory model](https://github.com/animalab/anima/blob/main/crates/anima-core/src/memory.rs): `crates/anima-core/src/memory.rs`
- [Namespace isolation](https://github.com/animalab/anima/blob/main/crates/anima-core/src/namespace.rs): `crates/anima-core/src/namespace.rs`

### Retrieval and models

- [Hybrid search](https://github.com/animalab/anima/blob/main/crates/anima-core/src/search.rs): `crates/anima-core/src/search.rs`
- [Temporal ranking](https://github.com/animalab/anima/blob/main/crates/anima-core/src/temporal.rs): `crates/anima-core/src/temporal.rs`
- [Embedding providers](https://github.com/animalab/anima/blob/main/crates/anima-embed/src/model.rs): `crates/anima-embed/src/model.rs`
- [Cross-encoder reranker](https://github.com/animalab/anima/blob/main/crates/anima-embed/src/reranker.rs): `crates/anima-embed/src/reranker.rs`

### Persistence

- [Memory store](https://github.com/animalab/anima/blob/main/crates/anima-db/src/store.rs): `crates/anima-db/src/store.rs`
- [SQLite pool and schema](https://github.com/animalab/anima/blob/main/crates/anima-db/src/pool.rs): `crates/anima-db/src/pool.rs`
- [Vector indexes](https://github.com/animalab/anima/blob/main/crates/anima-db/src/vector.rs): `crates/anima-db/src/vector.rs`
- [Keyword index](https://github.com/animalab/anima/blob/main/crates/anima-db/src/fts.rs): `crates/anima-db/src/fts.rs`

### Integration surfaces

- [Web console](https://github.com/animalab/anima/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web API client](https://github.com/animalab/anima/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [MCP bridge](https://github.com/animalab/anima/blob/main/mcp/src/index.ts): `mcp/src/index.ts`

### Other components

- **Assistant or user**
- **LLM provider**

## Connections

- Assistant or user → Web console: uses (evidence: `README.md`)
- Assistant or user → MCP bridge: uses (evidence: `README.md`)
- Assistant or user → HTTP server: calls REST API (evidence: `README.md`)
- HTTP server → API routing: starts (evidence: `crates/anima-server/src/main.rs`)
- API routing → Memory and chat handlers: routes requests (evidence: `crates/anima-server/src/app.rs`)
- Web console → Web API client: uses (evidence: `web/src/App.tsx`)
- Web API client → HTTP server: sends REST requests (evidence: `README.md`)
- MCP bridge → HTTP server: integrates via REST (evidence: `README.md`)
- HTTP server → Provider configuration: loads settings (evidence: `crates/anima-server/src/main.rs`)
- Memory and chat handlers → Memory store: reads and writes memories (evidence: `crates/anima-server/src/handlers.rs`)
- Memory store → SQLite pool and schema: uses SQLite pool (evidence: `crates/anima-db/src/store.rs`)
- SQLite pool and schema → Vector indexes: initializes vector tables (evidence: `crates/anima-db/src/pool.rs`)
- Memory store → Keyword index: uses keyword index (evidence: `crates/anima-db/src/store.rs`)
- Memory and chat handlers → Hybrid search: performs retrieval
- Hybrid search → Temporal ranking: uses temporal ranking (evidence: `crates/anima-core/src/search.rs`)
- Memory and chat handlers → Cross-encoder reranker: reranks candidates (evidence: `crates/anima-server/src/handlers.rs`)
- Memory and chat handlers → Embedding providers: requests embeddings
- Background processor → Memory consolidation: runs consolidation
- Memory and chat handlers → Background processor: queues processing (evidence: `crates/anima-server/src/handlers.rs`)
- Memory and chat handlers → Namespace isolation: enforces namespace scope
- Provider configuration → LLM provider: configures provider
- Memory consolidation → LLM provider: requests completions
- LLM provider → Memory consolidation: returns completions
