# verygoodplugins/automem architecture

> Architecture diagram of the GitHub repository verygoodplugins/automem, 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/verygoodplugins/automem
- Repository: https://github.com/verygoodplugins/automem

## Overview

AutoMem is a long-term memory service for AI assistants. Clients submit memories through REST or MCP; the service stores them in a graph and vector index, then recalls relevant memories using hybrid search and graph relationships. Optional background enrichment and consolidation add structure and maintain memory quality, while synchronization can repair index drift. The README documents these capabilities; some implementation relationships below are based on the SOURCE INDEX, so unsampled internals are not expanded beyond supported links.

Main entry points: [`automem/api/runtime_bootstrap.py`](https://github.com/verygoodplugins/automem/blob/develop/automem/api/runtime_bootstrap.py) (API Registration), [`automem/stores/vector_store.py`](https://github.com/verygoodplugins/automem/blob/develop/automem/stores/vector_store.py) (Qdrant Vectors), [`automem/stores/graph_store.py`](https://github.com/verygoodplugins/automem/blob/develop/automem/stores/graph_store.py) (FalkorDB Graph), [`automem/search/runtime_recall_helpers.py`](https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_recall_helpers.py) (Hybrid Recall)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Client Interfaces"]
  node_mcp["MCP Bridge<br/>[server.js]"]
end

subgraph group_service["Memory Service"]
  node_app["Flask Service<br/>[app.py]"]
  node_bootstrap["API Registration"]
  node_memory_api["Memory API<br/>[memory.py]"]
  node_recall_api["Recall API<br/>[recall.py]"]
  node_entity_api["Entity API<br/>[entity.py]"]
  node_graph_api["Graph API<br/>[graph.py]"]
  node_admin_api["Admin API<br/>[admin.py]"]
  node_stream_api["Streaming API<br/>[stream.py]"]
  node_config["Service Configuration<br/>[config.py]"]
end

subgraph group_processing["Memory Processing"]
  node_embedding["Embedding Providers<br/>[provider_init.py]"]
  node_enrichment["Enrichment Pipeline"]
  node_classification["Memory Classification"]
  node_consolidation["Consolidation Engine"]
end

subgraph group_storage["Storage and Search"]
  node_falkordb[("FalkorDB Graph<br/>[graph_store.py]")]
  node_qdrant[("Qdrant Vectors<br/>[vector_store.py]")]
  node_recall_search["Hybrid Recall"]
  node_relations["Relation Search"]
  node_keywords["Keyword Search"]
end

subgraph group_maintenance["Maintenance"]
  node_backup["Backup Operations<br/>[backup.py]"]
  node_sync["Index Sync Repair<br/>[runtime_worker.py]"]
end

node_assistant(("AI Assistant"))

node_assistant -->|"uses MCP"| node_mcp
node_assistant -->|"calls REST"| node_app
node_mcp -->|"forwards requests"| node_app
node_app -->|"wires routes"| node_bootstrap
node_bootstrap -->|"registers"| node_memory_api
node_bootstrap -->|"registers"| node_recall_api
node_bootstrap -->|"registers"| node_entity_api
node_bootstrap -->|"registers"| node_graph_api
node_bootstrap -->|"registers"| node_admin_api
node_bootstrap -->|"registers"| node_stream_api
node_memory_api -->|"stores canonical records"| node_falkordb
node_memory_api -->|"stores embeddings"| node_qdrant
node_recall_api -->|"runs retrieval"| node_recall_search
node_recall_search -->|"queries vectors"| node_qdrant
node_recall_search -->|"traverses graph"| node_falkordb
node_recall_search -.->|"expands relations"| node_relations
node_recall_search -.->|"uses keyword matching"| node_keywords
node_embedding -->|"provides vectors"| node_qdrant
node_enrichment -->|"adds structure"| node_falkordb
node_enrichment -->|"uses semantic search"| node_qdrant
node_consolidation -->|"consolidates memories"| node_falkordb
node_consolidation -->|"updates index"| node_qdrant
node_app -->|"imports classifier"| node_classification
node_enrichment -.->|"uses settings"| node_config
node_consolidation -->|"uses settings"| node_config
node_backup -.->|"backs up"| node_falkordb
node_backup -.->|"backs up"| node_qdrant
node_sync -->|"checks graph records"| node_falkordb
node_sync -->|"checks vector records"| node_qdrant
node_sync -->|"queues repair embeddings"| node_embedding

click node_mcp "https://github.com/verygoodplugins/automem/blob/develop/mcp-sse-server/server.js"
click node_app "https://github.com/verygoodplugins/automem/blob/develop/app.py"
click node_bootstrap "https://github.com/verygoodplugins/automem/blob/develop/automem/api/runtime_bootstrap.py"
click node_memory_api "https://github.com/verygoodplugins/automem/blob/develop/automem/api/memory.py"
click node_recall_api "https://github.com/verygoodplugins/automem/blob/develop/automem/api/recall.py"
click node_entity_api "https://github.com/verygoodplugins/automem/blob/develop/automem/api/entity.py"
click node_graph_api "https://github.com/verygoodplugins/automem/blob/develop/automem/api/graph.py"
click node_admin_api "https://github.com/verygoodplugins/automem/blob/develop/automem/api/admin.py"
click node_stream_api "https://github.com/verygoodplugins/automem/blob/develop/automem/api/stream.py"
click node_embedding "https://github.com/verygoodplugins/automem/blob/develop/automem/embedding/provider_init.py"
click node_enrichment "https://github.com/verygoodplugins/automem/blob/develop/automem/enrichment/runtime_orchestration.py"
click node_classification "https://github.com/verygoodplugins/automem/blob/develop/automem/classification/memory_classifier.py"
click node_consolidation "https://github.com/verygoodplugins/automem/blob/develop/automem/consolidation/identity_synthesis.py"
click node_falkordb "https://github.com/verygoodplugins/automem/blob/develop/automem/stores/graph_store.py"
click node_qdrant "https://github.com/verygoodplugins/automem/blob/develop/automem/stores/vector_store.py"
click node_recall_search "https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_recall_helpers.py"
click node_relations "https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_relations.py"
click node_keywords "https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_keywords.py"
click node_backup "https://github.com/verygoodplugins/automem/blob/develop/automem/backup.py"
click node_sync "https://github.com/verygoodplugins/automem/blob/develop/automem/sync/runtime_worker.py"
click node_config "https://github.com/verygoodplugins/automem/blob/develop/automem/config.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 toneBlue
class node_app,node_bootstrap,node_memory_api,node_recall_api,node_entity_api,node_graph_api,node_admin_api,node_stream_api,node_config toneAmber
class node_embedding,node_enrichment,node_classification,node_consolidation toneMint
class node_falkordb,node_qdrant,node_recall_search,node_relations,node_keywords toneRose
class node_backup,node_sync,node_assistant toneIndigo
```

## Components

### Client Interfaces

- [MCP Bridge](https://github.com/verygoodplugins/automem/blob/develop/mcp-sse-server/server.js): `mcp-sse-server/server.js`

### Memory Service

- [Flask Service](https://github.com/verygoodplugins/automem/blob/develop/app.py): `app.py`
- [API Registration](https://github.com/verygoodplugins/automem/blob/develop/automem/api/runtime_bootstrap.py): `automem/api/runtime_bootstrap.py`
- [Memory API](https://github.com/verygoodplugins/automem/blob/develop/automem/api/memory.py): `automem/api/memory.py`
- [Recall API](https://github.com/verygoodplugins/automem/blob/develop/automem/api/recall.py): `automem/api/recall.py`
- [Entity API](https://github.com/verygoodplugins/automem/blob/develop/automem/api/entity.py): `automem/api/entity.py`
- [Graph API](https://github.com/verygoodplugins/automem/blob/develop/automem/api/graph.py): `automem/api/graph.py`
- [Admin API](https://github.com/verygoodplugins/automem/blob/develop/automem/api/admin.py): `automem/api/admin.py`
- [Streaming API](https://github.com/verygoodplugins/automem/blob/develop/automem/api/stream.py): `automem/api/stream.py`
- [Service Configuration](https://github.com/verygoodplugins/automem/blob/develop/automem/config.py): `automem/config.py`

### Memory Processing

- [Embedding Providers](https://github.com/verygoodplugins/automem/blob/develop/automem/embedding/provider_init.py): `automem/embedding/provider_init.py`
- [Enrichment Pipeline](https://github.com/verygoodplugins/automem/blob/develop/automem/enrichment/runtime_orchestration.py): `automem/enrichment/runtime_orchestration.py`
- [Memory Classification](https://github.com/verygoodplugins/automem/blob/develop/automem/classification/memory_classifier.py): `automem/classification/memory_classifier.py`
- [Consolidation Engine](https://github.com/verygoodplugins/automem/blob/develop/automem/consolidation/identity_synthesis.py): `automem/consolidation/identity_synthesis.py`

### Storage and Search

- [FalkorDB Graph](https://github.com/verygoodplugins/automem/blob/develop/automem/stores/graph_store.py): `automem/stores/graph_store.py`
- [Qdrant Vectors](https://github.com/verygoodplugins/automem/blob/develop/automem/stores/vector_store.py): `automem/stores/vector_store.py`
- [Hybrid Recall](https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_recall_helpers.py): `automem/search/runtime_recall_helpers.py`
- [Relation Search](https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_relations.py): `automem/search/runtime_relations.py`
- [Keyword Search](https://github.com/verygoodplugins/automem/blob/develop/automem/search/runtime_keywords.py): `automem/search/runtime_keywords.py`

### Maintenance

- [Backup Operations](https://github.com/verygoodplugins/automem/blob/develop/automem/backup.py): `automem/backup.py`
- [Index Sync Repair](https://github.com/verygoodplugins/automem/blob/develop/automem/sync/runtime_worker.py): `automem/sync/runtime_worker.py`

### Other components

- **AI Assistant**

## Connections

- AI Assistant → MCP Bridge: uses MCP (evidence: `README.md`)
- AI Assistant → Flask Service: calls REST (evidence: `README.md`)
- MCP Bridge → Flask Service: forwards requests (evidence: `mcp-sse-server/server.js`)
- Flask Service → API Registration: wires routes (evidence: `app.py`)
- API Registration → Memory API: registers (evidence: `automem/api/runtime_bootstrap.py`)
- API Registration → Recall API: registers (evidence: `automem/api/runtime_bootstrap.py`)
- API Registration → Entity API: registers (evidence: `automem/api/runtime_bootstrap.py`)
- API Registration → Graph API: registers (evidence: `automem/api/runtime_bootstrap.py`)
- API Registration → Admin API: registers (evidence: `automem/api/runtime_bootstrap.py`)
- API Registration → Streaming API: registers (evidence: `automem/api/runtime_bootstrap.py`)
- Memory API → FalkorDB Graph: stores canonical records (evidence: `README.md`)
- Memory API → Qdrant Vectors: stores embeddings (evidence: `README.md`)
- Recall API → Hybrid Recall: runs retrieval (evidence: `README.md`)
- Hybrid Recall → Qdrant Vectors: queries vectors (evidence: `README.md`)
- Hybrid Recall → FalkorDB Graph: traverses graph (evidence: `README.md`)
- Hybrid Recall → Relation Search: expands relations
- Hybrid Recall → Keyword Search: uses keyword matching
- Embedding Providers → Qdrant Vectors: provides vectors (evidence: `README.md`)
- Enrichment Pipeline → FalkorDB Graph: adds structure (evidence: `README.md`)
- Enrichment Pipeline → Qdrant Vectors: uses semantic search (evidence: `README.md`)
- Consolidation Engine → FalkorDB Graph: consolidates memories (evidence: `README.md`)
- Consolidation Engine → Qdrant Vectors: updates index (evidence: `README.md`)
- Flask Service → Memory Classification: imports classifier (evidence: `app.py`)
- Enrichment Pipeline → Service Configuration: uses settings
- Consolidation Engine → Service Configuration: uses settings (evidence: `automem/consolidation/identity_synthesis.py`)
- Backup Operations → FalkorDB Graph: backs up (evidence: `README.md`)
- Backup Operations → Qdrant Vectors: backs up (evidence: `README.md`)
- Index Sync Repair → FalkorDB Graph: checks graph records (evidence: `automem/sync/runtime_worker.py`)
- Index Sync Repair → Qdrant Vectors: checks vector records (evidence: `automem/sync/runtime_worker.py`)
- Index Sync Repair → Embedding Providers: queues repair embeddings (evidence: `automem/sync/runtime_worker.py`)
