# doobidoo/mcp-memory-service architecture

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

- Interactive diagram: https://gitdiagram.com/doobidoo/mcp-memory-service
- Repository: https://github.com/doobidoo/mcp-memory-service

## Overview

mcp-memory-service is a self-hosted persistent memory backend for AI agents, exposed through REST, MCP, CLI, and a web dashboard. Clients submit memories or searches; shared memory logic stores, embeds, and retrieves relevant context across sessions, with optional graph reasoning and backend synchronization. Other documented capabilities include document ingestion, autonomous consolidation, OAuth-protected remote access, and SSE notifications. The graph follows README capabilities and the supplied tree; several subsystem links rely on documented roles because their implementation was not sampled.

Main entry points: [`src/mcp_memory_service/services/memory_service.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py) (Memory service), [`src/mcp_memory_service/web/api`](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/web/api) (REST endpoints), [`src/mcp_memory_service/storage/factory.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py) (Storage selection), [`src/mcp_memory_service/mcp_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Client access"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_rest["REST application<br/>[app.py]"]
  node_http_api["REST endpoints"]
  node_oauth["OAuth access"]
  node_cli["CLI<br/>[main.py]"]
  node_hooks["Claude hooks"]
  node_opencode["OpenCode plugin<br/>[memory-plugin.js]"]
end

subgraph group_memory["Memory lifecycle"]
  node_service["Memory service<br/>[memory_service.py]"]
  node_documents["Document ingestion"]
  node_harvest["Conversation harvest"]
end

subgraph group_intelligence["Memory intelligence"]
  node_embedding["Embedding models"]
  node_quality["Quality scoring"]
  node_reasoning["Search and reasoning"]
  node_graph["Knowledge graph<br/>[graph_service.py]"]
  node_consolidation["Consolidation"]
end

subgraph group_persistence["Persistence"]
  node_storage_factory["Storage selection<br/>[factory.py]"]
  node_storage[("Storage backends")]
  node_sync["Backend sync"]
end

subgraph group_operations["Web and operations"]
  node_dashboard["Web dashboard<br/>[app.js]"]
  node_events["SSE events<br/>[sse.py]"]
end

node_agents(("AI agents"))
node_web_users(("Dashboard users"))

node_agents -->|"invoke tools"| node_mcp
node_agents -->|"send requests"| node_rest
node_agents -->|"run commands"| node_cli
node_agents -.->|"trigger hooks"| node_hooks
node_agents -.->|"use plugin"| node_opencode
node_rest -->|"routes requests"| node_http_api
node_oauth -->|"authorizes"| node_http_api
node_mcp -->|"dispatches operations"| node_service
node_http_api -->|"dispatches operations"| node_service
node_cli -->|"selects storage"| node_storage_factory
node_service -->|"generates embeddings"| node_embedding
node_service -->|"scores memories"| node_quality
node_service -->|"retrieves context"| node_reasoning
node_service -->|"uses storage"| node_storage_factory
node_storage_factory -->|"creates backend"| node_storage
node_service -->|"manages relations"| node_graph
node_service -->|"consolidates memories"| node_consolidation
node_documents -->|"stores chunks"| node_storage_factory
node_harvest -.->|"captures memories"| node_service
node_sync -.->|"synchronizes data"| node_storage
node_web_users -->|"manage memories"| node_dashboard
node_dashboard -->|"calls endpoints"| node_http_api
node_http_api -->|"publishes changes"| node_events
node_events -->|"notifies clients"| node_agents

click node_mcp "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py"
click node_rest "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py"
click node_http_api "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/web/api"
click node_oauth "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/web/oauth"
click node_cli "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/cli/main.py"
click node_hooks "https://github.com/doobidoo/mcp-memory-service/tree/main/claude-hooks/core"
click node_opencode "https://github.com/doobidoo/mcp-memory-service/blob/main/opencode/memory-plugin.js"
click node_service "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py"
click node_documents "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/ingestion"
click node_harvest "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/harvest"
click node_embedding "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/embeddings"
click node_quality "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/quality"
click node_reasoning "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/reasoning"
click node_graph "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py"
click node_consolidation "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/consolidation"
click node_storage_factory "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py"
click node_storage "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/storage"
click node_sync "https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/sync"
click node_dashboard "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/static/app.js"
click node_events "https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/sse.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_rest,node_http_api,node_oauth,node_cli,node_hooks,node_opencode,node_web_users toneBlue
class node_service,node_documents,node_harvest toneAmber
class node_embedding,node_quality,node_reasoning,node_graph,node_consolidation toneMint
class node_storage_factory,node_storage,node_sync toneRose
class node_dashboard,node_events,node_agents toneIndigo
```

## Components

### Client access

- [MCP server](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py): `src/mcp_memory_service/mcp_server.py`
- [REST application](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py): `src/mcp_memory_service/web/app.py`
- [REST endpoints](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/web/api): `src/mcp_memory_service/web/api`
- [OAuth access](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/web/oauth): `src/mcp_memory_service/web/oauth`
- [CLI](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/cli/main.py): `src/mcp_memory_service/cli/main.py`
- [Claude hooks](https://github.com/doobidoo/mcp-memory-service/tree/main/claude-hooks/core): `claude-hooks/core`
- [OpenCode plugin](https://github.com/doobidoo/mcp-memory-service/blob/main/opencode/memory-plugin.js): `opencode/memory-plugin.js`

### Memory lifecycle

- [Memory service](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py): `src/mcp_memory_service/services/memory_service.py`
- [Document ingestion](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/ingestion): `src/mcp_memory_service/ingestion`
- [Conversation harvest](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/harvest): `src/mcp_memory_service/harvest`

### Memory intelligence

- [Embedding models](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/embeddings): `src/mcp_memory_service/embeddings`
- [Quality scoring](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/quality): `src/mcp_memory_service/quality`
- [Search and reasoning](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/reasoning): `src/mcp_memory_service/reasoning`
- [Knowledge graph](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py): `src/mcp_memory_service/services/graph_service.py`
- [Consolidation](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/consolidation): `src/mcp_memory_service/consolidation`

### Persistence

- [Storage selection](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py): `src/mcp_memory_service/storage/factory.py`
- [Storage backends](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/storage): `src/mcp_memory_service/storage`
- [Backend sync](https://github.com/doobidoo/mcp-memory-service/tree/main/src/mcp_memory_service/sync): `src/mcp_memory_service/sync`

### Web and operations

- [Web dashboard](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/static/app.js): `src/mcp_memory_service/web/static/app.js`
- [SSE events](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/sse.py): `src/mcp_memory_service/web/sse.py`

### Other components

- **AI agents**
- **Dashboard users**

## Connections

- AI agents → MCP server: invoke tools
- AI agents → REST application: send requests
- AI agents → CLI: run commands
- AI agents → Claude hooks: trigger hooks
- AI agents → OpenCode plugin: use plugin
- REST application → REST endpoints: routes requests
- OAuth access → REST endpoints: authorizes
- MCP server → Memory service: dispatches operations
- REST endpoints → Memory service: dispatches operations
- CLI → Storage selection: selects storage
- Memory service → Embedding models: generates embeddings
- Memory service → Quality scoring: scores memories
- Memory service → Search and reasoning: retrieves context
- Memory service → Storage selection: uses storage
- Storage selection → Storage backends: creates backend
- Memory service → Knowledge graph: manages relations
- Memory service → Consolidation: consolidates memories
- Document ingestion → Storage selection: stores chunks
- Conversation harvest → Memory service: captures memories
- Backend sync → Storage backends: synchronizes data
- Dashboard users → Web dashboard: manage memories
- Web dashboard → REST endpoints: calls endpoints
- REST endpoints → SSE events: publishes changes
- SSE events → AI agents: notifies clients