# ipiton/agent-memory-mcp architecture

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

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

## Overview

agent-memory-mcp is an engineering-context service for AI agents: MCP clients use its tools to capture and retrieve typed memory, search indexed project documents, inspect allowed repository files, and maintain knowledge across sessions. The principal workflow enters through the MCP server, dispatches tool requests to memory, RAG, or repository-search capabilities, and returns ranked or structured results; session-close analysis and stewardship add consolidation and review stages. README documents both stdio and HTTP transports and the major features. Some internal routing is unsampled, so those links are shown as unverified rather than asserted as inspected calls.

Main entry points: [`internal/server/server.go`](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/server/server.go) (MCP server), [`internal/memory/memory.go`](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/memory/memory.go) (Typed memory), [`internal/rag/vectorservice.go`](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/vectorservice.go) (Hybrid retrieval), [`internal/sessionclose/sessionclose.go`](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/sessionclose/sessionclose.go) (Session consolidation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry and tools"]
  node_server["MCP server<br/>[server.go]"]
  node_engineering_tools["Engineering tools"]
  node_repo_tools["Repo file tools<br/>[search.go]"]
end

subgraph group_memory["Memory lifecycle"]
  node_memory_store[("Typed memory<br/>[memory.go]")]
  node_session_close["Session consolidation<br/>[sessionclose.go]"]
  node_session_extract["Session extraction<br/>[extract.go]"]
  node_review["Review resolution<br/>[resolve.go]"]
  node_project_bank["Project bank views"]
end

subgraph group_retrieval["Search and retrieval"]
  node_rag_engine["Document RAG<br/>[rag.go]"]
  node_rag_indexer["Document indexer<br/>[indexer.go]"]
  node_vector_service["Hybrid retrieval<br/>[vectorservice.go]"]
end

subgraph group_maintenance["Capture and stewardship"]
  node_hooks["Session hooks<br/>[event.go]"]
  node_dedup["Capture deduplication<br/>[dedup.go]"]
  node_steward["Knowledge stewardship<br/>[steward.go]"]
  node_scanner["Drift scanner<br/>[scanner.go]"]
  node_archive["Archive sweep<br/>[archive_sweep.go]"]
end

subgraph group_platform["Storage and providers"]
  node_vector_store[("Vector index<br/>[vectorstore.go]")]
  node_keyword["Keyword ranking<br/>[keyword.go]"]
  node_embedding["Embedding providers<br/>[embedder.go]"]
  node_reranker["Neural reranker<br/>[reranker.go]"]
  node_path_guard["Path allowlist<br/>[paths.go]"]
  node_sqlite[("SQLite<br/>[sqlite.go]")]
end

node_client(("MCP client"))
node_cli["CLI<br/>[main.go]"]
node_engineer(("Engineering user"))

node_client -->|"sends requests"| node_server
node_engineer -->|"runs commands"| node_cli
node_cli -->|"starts service"| node_server
node_server -.->|"dispatches tools"| node_engineering_tools
node_server -->|"uses memory"| node_memory_store
node_server -->|"uses retrieval"| node_rag_engine
node_server -.->|"offers repo search"| node_repo_tools
node_engineering_tools -->|"stores knowledge"| node_memory_store
node_engineer -->|"searches files"| node_repo_tools
node_repo_tools -->|"checks allowed paths"| node_path_guard
node_rag_engine -.->|"indexes documents"| node_rag_indexer
node_rag_engine -.->|"retrieves candidates"| node_vector_service
node_vector_service -->|"queries index"| node_vector_store
node_vector_service -.->|"embeds queries"| node_embedding
node_vector_service -->|"reranks results"| node_reranker
node_vector_store -->|"maintains keywords"| node_keyword
node_vector_store -->|"persists chunks"| node_sqlite
node_memory_store -.->|"persists memories"| node_sqlite
node_hooks -.->|"filters captures"| node_dedup
node_session_close -.->|"extracts knowledge"| node_session_extract
node_session_close -->|"consolidates records"| node_memory_store
node_session_close -.->|"queues review"| node_review
node_steward -->|"runs scans"| node_scanner
node_scanner -->|"checks memories"| node_memory_store
node_archive -->|"updates lifecycle"| node_memory_store
node_server -.->|"provides maintenance"| node_steward
node_server -.->|"serves bank views"| node_project_bank

click node_cli "https://github.com/ipiton/agent-memory-mcp/blob/main/cmd/agent-memory-mcp/main.go"
click node_server "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/server/server.go"
click node_engineering_tools "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/server/tools_engineering.go"
click node_repo_tools "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/search/search.go"
click node_memory_store "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/memory/memory.go"
click node_session_close "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/sessionclose/sessionclose.go"
click node_session_extract "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/sessionclose/extract.go"
click node_review "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/review/resolve.go"
click node_project_bank "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/memory/projectbank_views.go"
click node_rag_engine "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/rag.go"
click node_rag_indexer "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/indexer.go"
click node_vector_service "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/vectorservice.go"
click node_vector_store "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/vectorstore/vectorstore.go"
click node_keyword "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/vectorstore/keyword.go"
click node_embedding "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/embedder/embedder.go"
click node_reranker "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/reranker/reranker.go"
click node_hooks "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/hooks/event.go"
click node_dedup "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/hooks/dedup.go"
click node_steward "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/steward/steward.go"
click node_scanner "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/steward/scanner.go"
click node_archive "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/lifecycle/archive_sweep.go"
click node_path_guard "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/paths/paths.go"
click node_sqlite "https://github.com/ipiton/agent-memory-mcp/blob/main/internal/dbutil/sqlite.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_server,node_engineering_tools,node_repo_tools,node_client,node_engineer toneBlue
class node_memory_store,node_session_close,node_session_extract,node_review,node_project_bank toneAmber
class node_rag_engine,node_rag_indexer,node_vector_service toneMint
class node_hooks,node_dedup,node_steward,node_scanner,node_archive toneRose
class node_vector_store,node_keyword,node_embedding,node_reranker,node_path_guard,node_sqlite toneIndigo
class node_cli toneTeal
```

## Components

### MCP entry and tools

- [MCP server](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/server/server.go): `internal/server/server.go`
- [Engineering tools](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/server/tools_engineering.go): `internal/server/tools_engineering.go`
- [Repo file tools](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/search/search.go): `internal/search/search.go`

### Memory lifecycle

- [Typed memory](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/memory/memory.go): `internal/memory/memory.go`
- [Session consolidation](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/sessionclose/sessionclose.go): `internal/sessionclose/sessionclose.go`
- [Session extraction](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/sessionclose/extract.go): `internal/sessionclose/extract.go`
- [Review resolution](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/review/resolve.go): `internal/review/resolve.go`
- [Project bank views](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/memory/projectbank_views.go): `internal/memory/projectbank_views.go`

### Search and retrieval

- [Document RAG](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/rag.go): `internal/rag/rag.go`
- [Document indexer](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/indexer.go): `internal/rag/indexer.go`
- [Hybrid retrieval](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/rag/vectorservice.go): `internal/rag/vectorservice.go`

### Capture and stewardship

- [Session hooks](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/hooks/event.go): `internal/hooks/event.go`
- [Capture deduplication](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/hooks/dedup.go): `internal/hooks/dedup.go`
- [Knowledge stewardship](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/steward/steward.go): `internal/steward/steward.go`
- [Drift scanner](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/steward/scanner.go): `internal/steward/scanner.go`
- [Archive sweep](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/lifecycle/archive_sweep.go): `internal/lifecycle/archive_sweep.go`

### Storage and providers

- [Vector index](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/vectorstore/vectorstore.go): `internal/vectorstore/vectorstore.go`
- [Keyword ranking](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/vectorstore/keyword.go): `internal/vectorstore/keyword.go`
- [Embedding providers](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/embedder/embedder.go): `internal/embedder/embedder.go`
- [Neural reranker](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/reranker/reranker.go): `internal/reranker/reranker.go`
- [Path allowlist](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/paths/paths.go): `internal/paths/paths.go`
- [SQLite](https://github.com/ipiton/agent-memory-mcp/blob/main/internal/dbutil/sqlite.go): `internal/dbutil/sqlite.go`

### Other components

- **MCP client**
- [CLI](https://github.com/ipiton/agent-memory-mcp/blob/main/cmd/agent-memory-mcp/main.go): `cmd/agent-memory-mcp/main.go`
- **Engineering user**

## Connections

- MCP client → MCP server: sends requests (evidence: `README.md`)
- Engineering user → CLI: runs commands (evidence: `README.md`)
- CLI → MCP server: starts service (evidence: `cmd/agent-memory-mcp/main.go`)
- MCP server → Engineering tools: dispatches tools
- MCP server → Typed memory: uses memory (evidence: `internal/server/server.go`)
- MCP server → Document RAG: uses retrieval (evidence: `internal/server/server.go`)
- MCP server → Repo file tools: offers repo search
- Engineering tools → Typed memory: stores knowledge (evidence: `internal/server/tools_engineering.go`)
- Engineering user → Repo file tools: searches files (evidence: `README.md`)
- Repo file tools → Path allowlist: checks allowed paths (evidence: `internal/search/search.go`)
- Document RAG → Document indexer: indexes documents
- Document RAG → Hybrid retrieval: retrieves candidates
- Hybrid retrieval → Vector index: queries index (evidence: `internal/rag/vectorservice.go`)
- Hybrid retrieval → Embedding providers: embeds queries
- Hybrid retrieval → Neural reranker: reranks results (evidence: `internal/rag/vectorservice.go`)
- Vector index → Keyword ranking: maintains keywords (evidence: `internal/vectorstore/vectorstore.go`)
- Vector index → SQLite: persists chunks (evidence: `internal/vectorstore/vectorstore.go`)
- Typed memory → SQLite: persists memories
- Session hooks → Capture deduplication: filters captures
- Session consolidation → Session extraction: extracts knowledge
- Session consolidation → Typed memory: consolidates records (evidence: `internal/sessionclose/sessionclose.go`)
- Session consolidation → Review resolution: queues review
- Knowledge stewardship → Drift scanner: runs scans (evidence: `internal/steward/steward.go`)
- Drift scanner → Typed memory: checks memories (evidence: `internal/steward/scanner.go`)
- Archive sweep → Typed memory: updates lifecycle (evidence: `internal/lifecycle/archive_sweep.go`)
- MCP server → Knowledge stewardship: provides maintenance
- MCP server → Project bank views: serves bank views