# abarbesgaard/sara architecture

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

- Interactive diagram: https://gitdiagram.com/abarbesgaard/sara
- Repository: https://github.com/abarbesgaard/sara
- Video tour (about a minute): https://gitdiagram.com/abarbesgaard/sara/video

## Overview

Sara is a local-first task and knowledge-memory system for AI agents, driven through a CLI or MCP tools. The main workflow is to capture project/task context, organize and execute work, then preserve findings for later recall; SQLite keeps that state across sessions. A separate web interface visualizes the memory graph. The graph emphasizes documented capabilities and sampled wiring; unsampled command internals are represented at their exact directories, and uncertain web-to-server wiring is left unasserted.

Main entry points: [`src/commands`](https://github.com/abarbesgaard/sara/tree/main/src/commands) (Task commands), [`dream-web/src/App.tsx`](https://github.com/abarbesgaard/sara/blob/main/dream-web/src/App.tsx) (Graph viewer app), [`src/infrastructure/db`](https://github.com/abarbesgaard/sara/tree/main/src/infrastructure/db) (SQLite persistence), [`dream-web/server/index.ts`](https://github.com/abarbesgaard/sara/blob/main/dream-web/server/index.ts) (Graph service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent interfaces"]
  node_cli["CLI parsing<br/>[cli.rs]"]
  node_dispatch["Command dispatch<br/>[dispatch.rs]"]
  node_mcp["MCP tools<br/>[server.rs]"]
end

subgraph group_tasks["Task workflow"]
  node_task_commands["Task commands"]
  node_guide["Guided work<br/>[mod.rs]"]
  node_task_models["Task models<br/>[model.rs]"]
  node_urgency["Urgency and ordering<br/>[mod.rs]"]
end

subgraph group_memory["Knowledge memory"]
  node_learn["Learn memories<br/>[mod.rs]"]
  node_recall["Recall and search"]
  node_memory_graph["Memory relationships<br/>[graph.rs]"]
  node_embeddings["Embedding index<br/>[embedding.rs]"]
  node_reflect["Memory reflection<br/>[mod.rs]"]
end

subgraph group_platform["Persistence and project context"]
  node_project_profile["Project profiles<br/>[mod.rs]"]
  node_git_context["Git integration<br/>[git.rs]"]
  node_database[("SQLite persistence")]
  node_config["Configuration<br/>[config.rs]"]
end

subgraph group_visual["Memory graph viewer"]
  node_web_app["Graph viewer app<br/>[App.tsx]"]
  node_web_api["Graph API client<br/>[api.ts]"]
  node_graph_view["3D graph<br/>[Graph3D.tsx]"]
  node_web_filters["Graph filters<br/>[Filters.tsx]"]
  node_side_panel["Memory details<br/>[SidePanel.tsx]"]
  node_web_server["Graph service<br/>[index.ts]"]
  node_graph_data["Graph assembly<br/>[graph.ts]"]
  node_web_db[("Viewer database access<br/>[db.ts]")]
  node_web_db_path["Database location<br/>[dbPath.ts]"]
end

node_agent(("Agent or human"))

node_agent -->|"invokes"| node_cli
node_cli -->|"parses and routes"| node_dispatch
node_dispatch -->|"dispatches commands"| node_task_commands
node_agent -->|"calls tools"| node_mcp
node_mcp -->|"routes tools"| node_task_commands
node_task_commands -.->|"persists task state"| node_database
node_task_commands -.->|"uses task records"| node_task_models
node_task_commands -->|"orders tasks"| node_urgency
node_task_commands -->|"supports guided work"| node_guide
node_project_profile -->|"stores project context"| node_database
node_project_profile -->|"detects project"| node_git_context
node_learn -->|"stores memories"| node_database
node_learn -->|"indexes findings"| node_embeddings
node_recall -->|"searches stored context"| node_database
node_recall -.->|"supports semantic search"| node_embeddings
node_reflect -->|"uses memory graph"| node_memory_graph
node_web_app -->|"fetches graph"| node_web_api
node_web_app -->|"renders graph"| node_graph_view
node_web_app -->|"filters graph"| node_web_filters
node_web_app -->|"shows selection"| node_side_panel
node_web_server -->|"assembles response"| node_graph_data
node_web_server -->|"accesses database"| node_web_db
node_web_server -->|"resolves location"| node_web_db_path

click node_cli "https://github.com/abarbesgaard/sara/blob/main/src/cli.rs"
click node_dispatch "https://github.com/abarbesgaard/sara/blob/main/src/dispatch.rs"
click node_mcp "https://github.com/abarbesgaard/sara/blob/main/src/mcp/server.rs"
click node_task_commands "https://github.com/abarbesgaard/sara/tree/main/src/commands"
click node_guide "https://github.com/abarbesgaard/sara/blob/main/src/commands/guide/mod.rs"
click node_task_models "https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/model.rs"
click node_urgency "https://github.com/abarbesgaard/sara/blob/main/src/commands/list/mod.rs"
click node_project_profile "https://github.com/abarbesgaard/sara/blob/main/src/commands/init/mod.rs"
click node_git_context "https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/git.rs"
click node_database "https://github.com/abarbesgaard/sara/tree/main/src/infrastructure/db"
click node_config "https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/config.rs"
click node_learn "https://github.com/abarbesgaard/sara/blob/main/src/commands/learn/mod.rs"
click node_recall "https://github.com/abarbesgaard/sara/tree/main/src/commands/recall"
click node_memory_graph "https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/memory/graph.rs"
click node_embeddings "https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/memory/embedding.rs"
click node_reflect "https://github.com/abarbesgaard/sara/blob/main/src/commands/reflect/mod.rs"
click node_web_app "https://github.com/abarbesgaard/sara/blob/main/dream-web/src/App.tsx"
click node_web_api "https://github.com/abarbesgaard/sara/blob/main/dream-web/src/api.ts"
click node_graph_view "https://github.com/abarbesgaard/sara/blob/main/dream-web/src/components/Graph3D.tsx"
click node_web_filters "https://github.com/abarbesgaard/sara/blob/main/dream-web/src/components/Filters.tsx"
click node_side_panel "https://github.com/abarbesgaard/sara/blob/main/dream-web/src/components/SidePanel.tsx"
click node_web_server "https://github.com/abarbesgaard/sara/blob/main/dream-web/server/index.ts"
click node_graph_data "https://github.com/abarbesgaard/sara/blob/main/dream-web/server/graph.ts"
click node_web_db "https://github.com/abarbesgaard/sara/blob/main/dream-web/server/db.ts"
click node_web_db_path "https://github.com/abarbesgaard/sara/blob/main/dream-web/server/dbPath.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_cli,node_dispatch,node_mcp toneBlue
class node_task_commands,node_guide,node_task_models,node_urgency toneAmber
class node_learn,node_recall,node_memory_graph,node_embeddings,node_reflect toneMint
class node_project_profile,node_git_context,node_database,node_config toneRose
class node_web_app,node_web_api,node_graph_view,node_web_filters,node_side_panel,node_web_server,node_graph_data,node_web_db,node_web_db_path,node_agent toneIndigo
```

## Components

### Agent interfaces

- [CLI parsing](https://github.com/abarbesgaard/sara/blob/main/src/cli.rs): `src/cli.rs`
- [Command dispatch](https://github.com/abarbesgaard/sara/blob/main/src/dispatch.rs): `src/dispatch.rs`
- [MCP tools](https://github.com/abarbesgaard/sara/blob/main/src/mcp/server.rs): `src/mcp/server.rs`

### Task workflow

- [Task commands](https://github.com/abarbesgaard/sara/tree/main/src/commands): `src/commands`
- [Guided work](https://github.com/abarbesgaard/sara/blob/main/src/commands/guide/mod.rs): `src/commands/guide/mod.rs`
- [Task models](https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/model.rs): `src/infrastructure/model.rs`
- [Urgency and ordering](https://github.com/abarbesgaard/sara/blob/main/src/commands/list/mod.rs): `src/commands/list/mod.rs`

### Knowledge memory

- [Learn memories](https://github.com/abarbesgaard/sara/blob/main/src/commands/learn/mod.rs): `src/commands/learn/mod.rs`
- [Recall and search](https://github.com/abarbesgaard/sara/tree/main/src/commands/recall): `src/commands/recall`
- [Memory relationships](https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/memory/graph.rs): `src/infrastructure/memory/graph.rs`
- [Embedding index](https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/memory/embedding.rs): `src/infrastructure/memory/embedding.rs`
- [Memory reflection](https://github.com/abarbesgaard/sara/blob/main/src/commands/reflect/mod.rs): `src/commands/reflect/mod.rs`

### Persistence and project context

- [Project profiles](https://github.com/abarbesgaard/sara/blob/main/src/commands/init/mod.rs): `src/commands/init/mod.rs`
- [Git integration](https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/git.rs): `src/infrastructure/git.rs`
- [SQLite persistence](https://github.com/abarbesgaard/sara/tree/main/src/infrastructure/db): `src/infrastructure/db`
- [Configuration](https://github.com/abarbesgaard/sara/blob/main/src/infrastructure/config.rs): `src/infrastructure/config.rs`

### Memory graph viewer

- [Graph viewer app](https://github.com/abarbesgaard/sara/blob/main/dream-web/src/App.tsx): `dream-web/src/App.tsx`
- [Graph API client](https://github.com/abarbesgaard/sara/blob/main/dream-web/src/api.ts): `dream-web/src/api.ts`
- [3D graph](https://github.com/abarbesgaard/sara/blob/main/dream-web/src/components/Graph3D.tsx): `dream-web/src/components/Graph3D.tsx`
- [Graph filters](https://github.com/abarbesgaard/sara/blob/main/dream-web/src/components/Filters.tsx): `dream-web/src/components/Filters.tsx`
- [Memory details](https://github.com/abarbesgaard/sara/blob/main/dream-web/src/components/SidePanel.tsx): `dream-web/src/components/SidePanel.tsx`
- [Graph service](https://github.com/abarbesgaard/sara/blob/main/dream-web/server/index.ts): `dream-web/server/index.ts`
- [Graph assembly](https://github.com/abarbesgaard/sara/blob/main/dream-web/server/graph.ts): `dream-web/server/graph.ts`
- [Viewer database access](https://github.com/abarbesgaard/sara/blob/main/dream-web/server/db.ts): `dream-web/server/db.ts`
- [Database location](https://github.com/abarbesgaard/sara/blob/main/dream-web/server/dbPath.ts): `dream-web/server/dbPath.ts`

### Other components

- **Agent or human**

## Connections

- Agent or human → CLI parsing: invokes (evidence: `README.md`)
- CLI parsing → Command dispatch: parses and routes (evidence: `src/main.rs`)
- Command dispatch → Task commands: dispatches commands (evidence: `src/dispatch.rs`)
- Agent or human → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → Task commands: routes tools (evidence: `src/mcp/guide.rs`)
- Task commands → SQLite persistence: persists task state (evidence: `README.md`)
- Task commands → Task models: uses task records (evidence: `src/commands/recall/search/query.rs`)
- Task commands → Urgency and ordering: orders tasks (evidence: `README.md`)
- Task commands → Guided work: supports guided work (evidence: `README.md`)
- Project profiles → SQLite persistence: stores project context (evidence: `README.md`)
- Project profiles → Git integration: detects project (evidence: `README.md`)
- Learn memories → SQLite persistence: stores memories (evidence: `src/commands/learn/mod.rs`)
- Learn memories → Embedding index: indexes findings (evidence: `src/commands/learn/mod.rs`)
- Recall and search → SQLite persistence: searches stored context (evidence: `src/commands/recall/search/query.rs`)
- Recall and search → Embedding index: supports semantic search (evidence: `README.md`)
- Memory reflection → Memory relationships: uses memory graph (evidence: `src/commands/reflect/mod.rs`)
- Graph viewer app → Graph API client: fetches graph (evidence: `dream-web/src/App.tsx`)
- Graph viewer app → 3D graph: renders graph (evidence: `dream-web/src/App.tsx`)
- Graph viewer app → Graph filters: filters graph (evidence: `dream-web/src/App.tsx`)
- Graph viewer app → Memory details: shows selection (evidence: `dream-web/src/App.tsx`)
- Graph service → Graph assembly: assembles response (evidence: `dream-web/server/index.ts`)
- Graph service → Viewer database access: accesses database (evidence: `dream-web/server/index.ts`)
- Graph service → Database location: resolves location (evidence: `dream-web/server/index.ts`)