# dustinspace217/mcp-memory-server architecture

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

- Interactive diagram: https://gitdiagram.com/dustinspace217/mcp-memory-server
- Repository: https://github.com/dustinspace217/mcp-memory-server

## Overview

MCP Memory Server exposes a knowledge-graph memory workflow: an MCP client writes entities, observations, and relations; the server persists versioned records in SQLite; and clients search or retrieve graph and session context. Embeddings and fused ranking support semantic retrieval. The repository also includes a Claude Code lifecycle harness and a companion graph visualizer. The sampled source confirms the server entry point, SQLite/embedding boundary, context-layer logic, and visualization data flow; other tool-level wiring is represented only where documented by the README.

Main entry points: [`sqlite-store.ts`](https://github.com/dustinspace217/mcp-memory-server/blob/main/sqlite-store.ts) (Memory store), [`viz/generate.py`](https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/generate.py) (Graph generator), [`index.ts`](https://github.com/dustinspace217/mcp-memory-server/blob/main/index.ts) (Tool handlers), [`embedding.ts`](https://github.com/dustinspace217/mcp-memory-server/blob/main/embedding.ts) (Embedding pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP memory server"]
  node_server_entry["Tool handlers<br/>[index.ts]"]
  node_sqlite[("Memory store<br/>[sqlite-store.ts]")]
  node_legacy_reader["JSONL migration reader<br/>[jsonl-reader.ts]"]
  node_name_normalizer["Name normalization<br/>[normalize-name.ts]"]
  node_embedding["Embedding pipeline<br/>[embedding.ts]"]
end

subgraph group_retrieval["Search and context"]
  node_search["Ranked search<br/>[rank-fusion.ts]"]
  node_context["Context layers<br/>[context-layers.ts]"]
end

subgraph group_harness["Session harness"]
  node_session_hooks["Context and continuity hooks"]
  node_freshness["Freshness scanning"]
  node_audit["Memory audit"]
end

subgraph group_visualization["Graph visualization"]
  node_visualizer["Graph generator<br/>[generate.py]"]
  node_entity_vectors["Entity vectors<br/>[entity_vectors.py]"]
  node_suggestions["Link suggestions<br/>[suggester.py]"]
  node_viewer["Graph viewer<br/>[template.html]"]
end

node_client(("MCP client"))
node_model["ONNX embedding model"]
node_user(("Memory user"))

node_client -->|"calls tools"| node_server_entry
node_server_entry -->|"reads and writes"| node_sqlite
node_server_entry -.->|"starts migration"| node_legacy_reader
node_sqlite -.->|"loads legacy graph"| node_legacy_reader
node_sqlite -->|"normalizes names"| node_name_normalizer
node_sqlite -->|"requests vectors"| node_embedding
node_embedding -->|"generates embeddings"| node_model
node_sqlite -->|"fuses search signals"| node_search
node_server_entry -->|"builds context layers"| node_context
node_session_hooks -->|"reads session context"| node_sqlite
node_freshness -->|"checks stored observations"| node_sqlite
node_audit -->|"reads memory records"| node_sqlite
node_user -->|"requests graph view"| node_visualizer
node_visualizer -->|"reads graph data"| node_sqlite
node_visualizer -->|"computes semantic vectors"| node_entity_vectors
node_visualizer -->|"finds unlinked neighbors"| node_suggestions
node_visualizer -->|"generates viewer data"| node_viewer
node_viewer -->|"displays graph"| node_user

click node_server_entry "https://github.com/dustinspace217/mcp-memory-server/blob/main/index.ts"
click node_sqlite "https://github.com/dustinspace217/mcp-memory-server/blob/main/sqlite-store.ts"
click node_legacy_reader "https://github.com/dustinspace217/mcp-memory-server/blob/main/jsonl-reader.ts"
click node_name_normalizer "https://github.com/dustinspace217/mcp-memory-server/blob/main/normalize-name.ts"
click node_embedding "https://github.com/dustinspace217/mcp-memory-server/blob/main/embedding.ts"
click node_search "https://github.com/dustinspace217/mcp-memory-server/blob/main/rank-fusion.ts"
click node_context "https://github.com/dustinspace217/mcp-memory-server/blob/main/context-layers.ts"
click node_session_hooks "https://github.com/dustinspace217/mcp-memory-server/tree/main/harness/hooks"
click node_freshness "https://github.com/dustinspace217/mcp-memory-server/blob/main/harness/hooks/check-memory-freshness.py"
click node_audit "https://github.com/dustinspace217/mcp-memory-server/blob/main/harness/audit/run-memory-audit.py"
click node_visualizer "https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/generate.py"
click node_entity_vectors "https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/entity_vectors.py"
click node_suggestions "https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/suggester.py"
click node_viewer "https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/template.html"

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_entry,node_sqlite,node_legacy_reader,node_name_normalizer,node_embedding,node_client,node_user toneBlue
class node_search,node_context toneAmber
class node_session_hooks,node_freshness,node_audit toneMint
class node_visualizer,node_entity_vectors,node_suggestions,node_viewer toneRose
class node_model toneIndigo
```

## Components

### MCP memory server

- [Tool handlers](https://github.com/dustinspace217/mcp-memory-server/blob/main/index.ts): `index.ts`
- [Memory store](https://github.com/dustinspace217/mcp-memory-server/blob/main/sqlite-store.ts): `sqlite-store.ts`
- [JSONL migration reader](https://github.com/dustinspace217/mcp-memory-server/blob/main/jsonl-reader.ts): `jsonl-reader.ts`
- [Name normalization](https://github.com/dustinspace217/mcp-memory-server/blob/main/normalize-name.ts): `normalize-name.ts`
- [Embedding pipeline](https://github.com/dustinspace217/mcp-memory-server/blob/main/embedding.ts): `embedding.ts`

### Search and context

- [Ranked search](https://github.com/dustinspace217/mcp-memory-server/blob/main/rank-fusion.ts): `rank-fusion.ts`
- [Context layers](https://github.com/dustinspace217/mcp-memory-server/blob/main/context-layers.ts): `context-layers.ts`

### Session harness

- [Context and continuity hooks](https://github.com/dustinspace217/mcp-memory-server/tree/main/harness/hooks): `harness/hooks`
- [Freshness scanning](https://github.com/dustinspace217/mcp-memory-server/blob/main/harness/hooks/check-memory-freshness.py): `harness/hooks/check-memory-freshness.py`
- [Memory audit](https://github.com/dustinspace217/mcp-memory-server/blob/main/harness/audit/run-memory-audit.py): `harness/audit/run-memory-audit.py`

### Graph visualization

- [Graph generator](https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/generate.py): `viz/generate.py`
- [Entity vectors](https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/entity_vectors.py): `viz/entity_vectors.py`
- [Link suggestions](https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/suggester.py): `viz/suggester.py`
- [Graph viewer](https://github.com/dustinspace217/mcp-memory-server/blob/main/viz/template.html): `viz/template.html`

### Other components

- **MCP client**
- **ONNX embedding model**
- **Memory user**

## Connections

- MCP client → Tool handlers: calls tools
- Tool handlers → Memory store: reads and writes
- Tool handlers → JSONL migration reader: starts migration
- Memory store → JSONL migration reader: loads legacy graph
- Memory store → Name normalization: normalizes names
- Memory store → Embedding pipeline: requests vectors
- Embedding pipeline → ONNX embedding model: generates embeddings
- Memory store → Ranked search: fuses search signals
- Tool handlers → Context layers: builds context layers
- Context and continuity hooks → Memory store: reads session context
- Freshness scanning → Memory store: checks stored observations
- Memory audit → Memory store: reads memory records
- Memory user → Graph generator: requests graph view
- Graph generator → Memory store: reads graph data
- Graph generator → Entity vectors: computes semantic vectors
- Graph generator → Link suggestions: finds unlinked neighbors
- Graph generator → Graph viewer: generates viewer data
- Graph viewer → Memory user: displays graph