# dp9318/recall architecture

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

- Interactive diagram: https://gitdiagram.com/dp9318/recall
- Repository: https://github.com/dp9318/recall

## Overview

RECALL is a local persistent memory engine for AI coding agents, exposed through an MCP server and a REST API with a web dashboard. The principal workflow captures project context, stores it canonically, retrieves relevant memories, resolves conflicts under instruction authority, and returns assembled context to an agent. The graph includes documented major capabilities such as lineage/compaction and dashboard management; unsampled routes and implementation details are represented at subsystem level, with uncertain links omitted.

Main entry points: [`recall_core/memory_manager.py`](https://github.com/dp9318/recall/blob/master/recall_core/memory_manager.py) (Memory Manager), [`recall_core/bootstrap.py`](https://github.com/dp9318/recall/blob/master/recall_core/bootstrap.py) (Core Bootstrap), [`intelligence/retrieval.py`](https://github.com/dp9318/recall/blob/master/intelligence/retrieval.py) (Hybrid Retrieval), [`database/repositories`](https://github.com/dp9318/recall/tree/master/database/repositories) (SQLite Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent & User Interfaces"]
  node_mcp["MCP Tools<br/>[server.py]"]
end

subgraph group_api["HTTP &amp; Dashboard"]
  node_web_app["Dashboard Pages"]
  node_web_client["API Client<br/>[client.ts]"]
  node_api_app["REST Application<br/>[app.py]"]
  node_api_routes["REST Routes"]
end

subgraph group_core["Memory Core"]
  node_bootstrap["Core Bootstrap<br/>[bootstrap.py]"]
  node_manager["Memory Manager<br/>[memory_manager.py]"]
  node_context["Context Assembly"]
  node_instructions["Instruction Service"]
  node_contracts["Domain Contracts"]
end

subgraph group_intelligence["Retrieval &amp; Arbitration"]
  node_retrieval["Hybrid Retrieval<br/>[retrieval.py]"]
  node_conflict["Conflict Resolution<br/>[conflict.py]"]
  node_embeddings["Embedding Service<br/>[embeddings.py]"]
end

subgraph group_persistence["Persistence"]
  node_repositories["SQLite Repositories"]
  node_sqlite[("SQLite Ledger<br/>[connection.py]")]
  node_semantic_index[("Semantic Index")]
end

node_agent(("AI Agent"))
node_dashboard_user(("Dashboard User"))
node_chroma[("ChromaDB")]
node_local_llm["Local LLM"]

node_agent -->|"uses tools"| node_mcp
node_mcp -->|"initializes core"| node_bootstrap
node_mcp -->|"calls operations"| node_manager
node_dashboard_user -->|"manages memory"| node_web_app
node_web_app -->|"requests data"| node_web_client
node_web_client -->|"calls REST"| node_api_app
node_api_app -->|"registers routers"| node_api_routes
node_api_routes -->|"invokes operations"| node_manager
node_api_app -->|"accepts manager"| node_manager
node_bootstrap -->|"constructs"| node_manager
node_bootstrap -->|"composes storage"| node_repositories
node_bootstrap -->|"composes service"| node_retrieval
node_bootstrap -->|"composes service"| node_conflict
node_bootstrap -->|"composes service"| node_embeddings
node_manager -->|"reads and writes"| node_repositories
node_manager -->|"retrieves memories"| node_retrieval
node_manager -->|"resolves conflicts"| node_conflict
node_manager -->|"delegates instructions"| node_instructions
node_manager -->|"assembles context"| node_context
node_manager -->|"cleans derived index"| node_semantic_index
node_retrieval -->|"searches vectors"| node_semantic_index
node_retrieval -->|"searches structured"| node_repositories
node_repositories -->|"persists records"| node_sqlite
node_semantic_index -.->|"indexes vectors"| node_chroma
node_embeddings -.->|"embeds content"| node_chroma
node_conflict -.->|"arbitrates ambiguity"| node_local_llm
node_context -->|"returns assembled context"| node_contracts
node_manager -->|"uses domain types"| node_contracts

click node_mcp "https://github.com/dp9318/recall/blob/master/recall_mcp/server.py"
click node_web_app "https://github.com/dp9318/recall/tree/master/frontend/src/pages"
click node_web_client "https://github.com/dp9318/recall/blob/master/frontend/src/api/client.ts"
click node_api_app "https://github.com/dp9318/recall/blob/master/api/app.py"
click node_api_routes "https://github.com/dp9318/recall/tree/master/api/routes"
click node_bootstrap "https://github.com/dp9318/recall/blob/master/recall_core/bootstrap.py"
click node_manager "https://github.com/dp9318/recall/blob/master/recall_core/memory_manager.py"
click node_context "https://github.com/dp9318/recall/blob/master/recall_core/context_assembly.py"
click node_instructions "https://github.com/dp9318/recall/blob/master/recall_core/instruction_service.py"
click node_retrieval "https://github.com/dp9318/recall/blob/master/intelligence/retrieval.py"
click node_conflict "https://github.com/dp9318/recall/blob/master/intelligence/conflict.py"
click node_embeddings "https://github.com/dp9318/recall/blob/master/intelligence/embeddings.py"
click node_contracts "https://github.com/dp9318/recall/tree/master/contracts"
click node_repositories "https://github.com/dp9318/recall/tree/master/database/repositories"
click node_sqlite "https://github.com/dp9318/recall/blob/master/database/connection.py"
click node_semantic_index "https://github.com/dp9318/recall/blob/master/database/repositories/semantic_index_repo.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_mcp,node_dashboard_user toneBlue
class node_web_app,node_web_client,node_api_app,node_api_routes,node_chroma toneAmber
class node_bootstrap,node_manager,node_context,node_instructions,node_contracts toneMint
class node_retrieval,node_conflict,node_embeddings toneRose
class node_repositories,node_sqlite,node_semantic_index,node_agent,node_local_llm toneIndigo
```

## Components

### Agent & User Interfaces

- [MCP Tools](https://github.com/dp9318/recall/blob/master/recall_mcp/server.py): `recall_mcp/server.py`

### HTTP & Dashboard

- [Dashboard Pages](https://github.com/dp9318/recall/tree/master/frontend/src/pages): `frontend/src/pages`
- [API Client](https://github.com/dp9318/recall/blob/master/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [REST Application](https://github.com/dp9318/recall/blob/master/api/app.py): `api/app.py`
- [REST Routes](https://github.com/dp9318/recall/tree/master/api/routes): `api/routes`

### Memory Core

- [Core Bootstrap](https://github.com/dp9318/recall/blob/master/recall_core/bootstrap.py): `recall_core/bootstrap.py`
- [Memory Manager](https://github.com/dp9318/recall/blob/master/recall_core/memory_manager.py): `recall_core/memory_manager.py`
- [Context Assembly](https://github.com/dp9318/recall/blob/master/recall_core/context_assembly.py): `recall_core/context_assembly.py`
- [Instruction Service](https://github.com/dp9318/recall/blob/master/recall_core/instruction_service.py): `recall_core/instruction_service.py`
- [Domain Contracts](https://github.com/dp9318/recall/tree/master/contracts): `contracts`

### Retrieval & Arbitration

- [Hybrid Retrieval](https://github.com/dp9318/recall/blob/master/intelligence/retrieval.py): `intelligence/retrieval.py`
- [Conflict Resolution](https://github.com/dp9318/recall/blob/master/intelligence/conflict.py): `intelligence/conflict.py`
- [Embedding Service](https://github.com/dp9318/recall/blob/master/intelligence/embeddings.py): `intelligence/embeddings.py`

### Persistence

- [SQLite Repositories](https://github.com/dp9318/recall/tree/master/database/repositories): `database/repositories`
- [SQLite Ledger](https://github.com/dp9318/recall/blob/master/database/connection.py): `database/connection.py`
- [Semantic Index](https://github.com/dp9318/recall/blob/master/database/repositories/semantic_index_repo.py): `database/repositories/semantic_index_repo.py`

### Other components

- **AI Agent**
- **Dashboard User**
- **ChromaDB**
- **Local LLM**

## Connections

- AI Agent → MCP Tools: uses tools (evidence: `README.md`)
- MCP Tools → Core Bootstrap: initializes core (evidence: `recall_mcp/server.py`)
- MCP Tools → Memory Manager: calls operations (evidence: `recall_mcp/server.py`)
- Dashboard User → Dashboard Pages: manages memory (evidence: `README.md`)
- Dashboard Pages → API Client: requests data (evidence: `frontend/src/pages/SettingsPage.tsx`)
- API Client → REST Application: calls REST (evidence: `README.md`)
- REST Application → REST Routes: registers routers (evidence: `api/app.py`)
- REST Routes → Memory Manager: invokes operations (evidence: `api/routes/context.py`)
- REST Application → Memory Manager: accepts manager (evidence: `api/app.py`)
- Core Bootstrap → Memory Manager: constructs (evidence: `recall_core/bootstrap.py`)
- Core Bootstrap → SQLite Repositories: composes storage (evidence: `recall_core/bootstrap.py`)
- Core Bootstrap → Hybrid Retrieval: composes service (evidence: `recall_core/bootstrap.py`)
- Core Bootstrap → Conflict Resolution: composes service (evidence: `recall_core/bootstrap.py`)
- Core Bootstrap → Embedding Service: composes service (evidence: `recall_core/bootstrap.py`)
- Memory Manager → SQLite Repositories: reads and writes (evidence: `recall_core/memory_manager.py`)
- Memory Manager → Hybrid Retrieval: retrieves memories (evidence: `recall_core/memory_manager.py`)
- Memory Manager → Conflict Resolution: resolves conflicts (evidence: `recall_core/memory_manager.py`)
- Memory Manager → Instruction Service: delegates instructions (evidence: `recall_core/memory_manager.py`)
- Memory Manager → Context Assembly: assembles context (evidence: `recall_core/memory_manager.py`)
- Memory Manager → Semantic Index: cleans derived index (evidence: `recall_core/memory_manager.py`)
- Hybrid Retrieval → Semantic Index: searches vectors (evidence: `intelligence/retrieval.py`)
- Hybrid Retrieval → SQLite Repositories: searches structured (evidence: `intelligence/retrieval.py`)
- SQLite Repositories → SQLite Ledger: persists records (evidence: `database/connection.py`)
- Semantic Index → ChromaDB: indexes vectors (evidence: `README.md`)
- Embedding Service → ChromaDB: embeds content (evidence: `README.md`)
- Conflict Resolution → Local LLM: arbitrates ambiguity (evidence: `README.md`)
- Context Assembly → Domain Contracts: returns assembled context (evidence: `recall_core/context_assembly.py`)
- Memory Manager → Domain Contracts: uses domain types (evidence: `recall_core/memory_manager.py`)