# taimufuraiyaa/agent-memory architecture

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

- Interactive diagram: https://gitdiagram.com/taimufuraiyaa/agent-memory
- Repository: https://github.com/taimufuraiyaa/agent-memory

## Overview

agent-memory is a persistent memory layer for coding agents, with local-first and hosted interfaces. The principal local workflow registers a workspace, accepts memory writes, and returns ranked, token-budgeted recall for an agent. Its domain stages include hybrid persistence, retrieval and context assembly; additional documented capabilities include graph expansion, exact-term search, and agent integrations. The tree and excerpts also show a hosted API and worker/reconciliation services. Some hosted modules are unsampled, so their internal connections are represented only where the API entry point or documentation supports them.

Main entry points: [`internal/engine/write_pipeline.go`](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/write_pipeline.go) (Write pipeline), [`cmd/agent-memory-api/main.go`](https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-api/main.go) (Hosted API), [`internal/cli/commands.go`](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/cli/commands.go) (CLI commands), [`internal/application/recall.go`](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/application/recall.go) (Recall service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local workspace"]
  node_cli["CLI commands<br/>[commands.go]"]
  node_workspace["Workspace manager<br/>[manager.go]"]
  node_api["Local HTTP API<br/>[server.go]"]
  node_recall_handler["Recall endpoint<br/>[recall_pipeline.go]"]
end

subgraph group_memory["Memory engine"]
  node_write["Write pipeline<br/>[write_pipeline.go]"]
  node_recall["Recall service<br/>[recall.go]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.go]"]
  node_assembly["Context assembly<br/>[recall_assembly.go]"]
  node_graph_search["Graph expansion<br/>[knowledge_graph.go]"]
  node_term_search["Exact-term search<br/>[term_search.go]"]
  node_sqlite[("SQLite memory store<br/>[store.go]")]
  node_markdown["Markdown tier<br/>[adapter.go]"]
  node_embeddings["Embedding provider<br/>[provider.go]"]
end

subgraph group_hosted["Hosted service"]
  node_hosted_api["Hosted API<br/>[main.go]"]
  node_hosted_memory["Tenant memory<br/>[service.go]"]
  node_hosted_retrieval["Hosted retrieval<br/>[service.go]"]
  node_source_ingest["Source ingestion<br/>[upload.go]"]
  node_worker["Background worker<br/>[main.go]"]
  node_reconciler["Reconciliation<br/>[main.go]"]
end

subgraph group_clients["Agent interfaces"]
  node_integration["Agent integrations<br/>[registry.go]"]
  node_dashboard["Dashboard<br/>[main.tsx]"]
end

node_agent(("Coding agent"))

node_agent -->|"invokes"| node_cli
node_cli -.->|"manages workspaces"| node_workspace
node_workspace -->|"opens databases"| node_sqlite
node_agent -.->|"requests memory"| node_api
node_api -.->|"routes recall"| node_recall_handler
node_recall_handler -->|"calls recall"| node_recall
node_recall -.->|"retrieves candidates"| node_retrieval
node_retrieval -.->|"reads memories"| node_sqlite
node_recall -.->|"assembles context"| node_assembly
node_agent -.->|"writes memories"| node_cli
node_cli -.->|"submits writes"| node_write
node_write -->|"persists entries"| node_sqlite
node_write -->|"eagerly embeds"| node_embeddings
node_write -.->|"supports tier hook"| node_markdown
node_retrieval -.->|"expands relations"| node_graph_search
node_agent -.->|"searches terms"| node_term_search
node_agent -->|"connects through"| node_integration
node_agent -->|"uses dashboard"| node_dashboard
node_agent -.->|"uses hosted service"| node_hosted_api
node_hosted_api -->|"configures service"| node_hosted_memory
node_hosted_api -->|"configures search"| node_hosted_retrieval
node_hosted_api -->|"configures uploads"| node_source_ingest
node_worker -->|"processes sources"| node_source_ingest
node_reconciler -->|"reconciles vault"| node_source_ingest

click node_cli "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/cli/commands.go"
click node_workspace "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/workspace/manager.go"
click node_api "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/api/server.go"
click node_recall_handler "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/api/recall_pipeline.go"
click node_write "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/write_pipeline.go"
click node_recall "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/application/recall.go"
click node_retrieval "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/retrieval.go"
click node_assembly "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/recall_assembly.go"
click node_graph_search "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/knowledge_graph.go"
click node_term_search "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/application/term_search.go"
click node_sqlite "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/storage/sqlite/store.go"
click node_markdown "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/storage/markdown/adapter.go"
click node_embeddings "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/embeddings/provider.go"
click node_integration "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/integration/registry.go"
click node_dashboard "https://github.com/taimufuraiyaa/agent-memory/blob/main/tools/agent-memory/dashboard/src/main.tsx"
click node_hosted_api "https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-api/main.go"
click node_hosted_memory "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/saas/memory/service.go"
click node_hosted_retrieval "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/saas/retrieval/service.go"
click node_source_ingest "https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/saas/source/upload.go"
click node_worker "https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-worker/main.go"
click node_reconciler "https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-reconciler/main.go"

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_workspace,node_api,node_recall_handler toneBlue
class node_write,node_recall,node_retrieval,node_assembly,node_graph_search,node_term_search,node_sqlite,node_markdown,node_embeddings toneAmber
class node_hosted_api,node_hosted_memory,node_hosted_retrieval,node_source_ingest,node_worker,node_reconciler toneMint
class node_integration,node_dashboard toneRose
class node_agent toneIndigo
```

## Components

### Local workspace

- [CLI commands](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/cli/commands.go): `internal/cli/commands.go`
- [Workspace manager](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/workspace/manager.go): `internal/workspace/manager.go`
- [Local HTTP API](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/api/server.go): `internal/api/server.go`
- [Recall endpoint](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/api/recall_pipeline.go): `internal/api/recall_pipeline.go`

### Memory engine

- [Write pipeline](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/write_pipeline.go): `internal/engine/write_pipeline.go`
- [Recall service](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/application/recall.go): `internal/application/recall.go`
- [Hybrid retrieval](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/retrieval.go): `internal/engine/retrieval.go`
- [Context assembly](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/recall_assembly.go): `internal/engine/recall_assembly.go`
- [Graph expansion](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/engine/knowledge_graph.go): `internal/engine/knowledge_graph.go`
- [Exact-term search](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/application/term_search.go): `internal/application/term_search.go`
- [SQLite memory store](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/storage/sqlite/store.go): `internal/storage/sqlite/store.go`
- [Markdown tier](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/storage/markdown/adapter.go): `internal/storage/markdown/adapter.go`
- [Embedding provider](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/embeddings/provider.go): `internal/embeddings/provider.go`

### Hosted service

- [Hosted API](https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-api/main.go): `cmd/agent-memory-api/main.go`
- [Tenant memory](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/saas/memory/service.go): `internal/saas/memory/service.go`
- [Hosted retrieval](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/saas/retrieval/service.go): `internal/saas/retrieval/service.go`
- [Source ingestion](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/saas/source/upload.go): `internal/saas/source/upload.go`
- [Background worker](https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-worker/main.go): `cmd/agent-memory-worker/main.go`
- [Reconciliation](https://github.com/taimufuraiyaa/agent-memory/blob/main/cmd/agent-memory-reconciler/main.go): `cmd/agent-memory-reconciler/main.go`

### Agent interfaces

- [Agent integrations](https://github.com/taimufuraiyaa/agent-memory/blob/main/internal/integration/registry.go): `internal/integration/registry.go`
- [Dashboard](https://github.com/taimufuraiyaa/agent-memory/blob/main/tools/agent-memory/dashboard/src/main.tsx): `tools/agent-memory/dashboard/src/main.tsx`

### Other components

- **Coding agent**

## Connections

- Coding agent → CLI commands: invokes (evidence: `README.md`)
- CLI commands → Workspace manager: manages workspaces
- Workspace manager → SQLite memory store: opens databases (evidence: `internal/workspace/manager.go`)
- Coding agent → Local HTTP API: requests memory
- Local HTTP API → Recall endpoint: routes recall
- Recall endpoint → Recall service: calls recall (evidence: `internal/api/recall_pipeline.go`)
- Recall service → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → SQLite memory store: reads memories
- Recall service → Context assembly: assembles context
- Coding agent → CLI commands: writes memories
- CLI commands → Write pipeline: submits writes
- Write pipeline → SQLite memory store: persists entries (evidence: `internal/engine/write_pipeline.go`)
- Write pipeline → Embedding provider: eagerly embeds (evidence: `internal/engine/write_pipeline.go`)
- Write pipeline → Markdown tier: supports tier hook
- Hybrid retrieval → Graph expansion: expands relations
- Coding agent → Exact-term search: searches terms
- Coding agent → Agent integrations: connects through (evidence: `README.md`)
- Coding agent → Dashboard: uses dashboard (evidence: `README.md`)
- Coding agent → Hosted API: uses hosted service
- Hosted API → Tenant memory: configures service (evidence: `cmd/agent-memory-api/main.go`)
- Hosted API → Hosted retrieval: configures search (evidence: `cmd/agent-memory-api/main.go`)
- Hosted API → Source ingestion: configures uploads (evidence: `cmd/agent-memory-api/main.go`)
- Background worker → Source ingestion: processes sources (evidence: `cmd/agent-memory-worker/main.go`)
- Reconciliation → Source ingestion: reconciles vault (evidence: `cmd/agent-memory-reconciler/main.go`)
