# mnemosyne-oss/mnemosyne architecture

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

- Interactive diagram: https://gitdiagram.com/mnemosyne-oss/mnemosyne
- Repository: https://github.com/mnemosyne-oss/mnemosyne

## Overview

Mnemosyne is a local-first, SQLite-backed memory layer for agents. The main workflow is an agent storing a memory, then recalling relevant context; the runtime also supports fact extraction, multi-tier and canonical memory, consolidation, and agent-facing integrations. Groups distinguish interfaces, memory processing, retrieval, and persistence/operations. README statements and the supplied source excerpts/index support the shown relationships; unsampled subsystems are included where documented, but their internal calls are not inferred.

Main entry points: [`mnemosyne/core/memory.py`](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/memory.py) (Memory API), [`mnemosyne/core/beam.py`](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/beam.py) (BEAM Recall), [`mnemosyne/core/embeddings.py`](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/embeddings.py) (Dense Embeddings), [`mnemosyne/batch_tool.py`](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/batch_tool.py) (Batch Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent Interfaces"]
  node_sdk["Python SDK<br/>[__init__.py]"]
  node_mcp["MCP Tools<br/>[mcp_tools.py]"]
  node_cli["Command Line<br/>[cli.py]"]
  node_hermes["Hermes Provider<br/>[__init__.py]"]
  node_openwebui["OpenWebUI Bridge<br/>[openwebui_tool.py]"]
  node_openclaw["OpenClaw Provider<br/>[openclaw.py]"]
  node_vscode["VS Code Extension<br/>[client.ts]"]
  node_obsidian["Obsidian Plugin<br/>[main.ts]"]
end

subgraph group_processing["Memory Processing"]
  node_extraction["Fact Extraction<br/>[client.py]"]
  node_writefilters["Write Filtering<br/>[filters.py]"]
  node_memory["Memory API<br/>[memory.py]"]
  node_batch["Batch Operations<br/>[batch_tool.py]"]
  node_consolidation["Veracity Consolidation"]
  node_canonical[("Canonical Facts<br/>[canonical.py]")]
  node_episodic[("Episodic Graph<br/>[episodic_graph.py]")]
  node_content["Content Canonicalization<br/>[canonical.py]"]
end

subgraph group_retrieval["Recall and Retrieval"]
  node_beam["BEAM Recall<br/>[beam.py]"]
  node_embeddings["Dense Embeddings<br/>[embeddings.py]"]
  node_triples["Memory Triples<br/>[triples.py]"]
  node_annotations["Annotations<br/>[annotations.py]"]
end

subgraph group_state["State and Operations"]
  node_banks[("Memory Banks<br/>[banks.py]")]
  node_journal[("Journal<br/>[journal.py]")]
  node_config["Runtime Configuration<br/>[config.py]"]
  node_importers["Memory Importers<br/>[__init__.py]"]
  node_sync["Instance Sync<br/>[sync.py]"]
  node_diagnostics["Recall Diagnostics"]
  node_modelrefresh["Model Refresh<br/>[model_refresh.py]"]
  node_useragent["User and Agent Context<br/>[user_agent.py]"]
  node_doctor["Health Diagnostics<br/>[diagnose.py]"]
end

node_agent(("Agent or User"))

node_agent -->|"calls"| node_sdk
node_sdk -->|"stores or recalls"| node_memory
node_agent -->|"uses"| node_mcp
node_mcp -.->|"accesses memory"| node_memory
node_agent -->|"runs commands"| node_cli
node_cli -.->|"stores or recalls"| node_memory
node_agent -->|"uses provider"| node_hermes
node_hermes -->|"accesses memory"| node_memory
node_agent -->|"uses tool"| node_openwebui
node_openwebui -->|"calls"| node_memory
node_agent -->|"uses provider"| node_openclaw
node_agent -.->|"uses extension"| node_vscode
node_agent -.->|"uses plugin"| node_obsidian
node_memory -->|"filters writes"| node_writefilters
node_memory -->|"delegates recall"| node_beam
node_memory -->|"uses vectors"| node_embeddings
node_memory -->|"uses banks"| node_banks
node_memory -->|"records changes"| node_journal
node_memory -->|"uses triples"| node_triples
node_memory -->|"uses annotations"| node_annotations
node_memory -->|"uses canonicalization"| node_content
node_memory -->|"uses graph"| node_episodic
node_batch -->|"uses recall"| node_beam
node_batch -->|"uses consolidation"| node_consolidation
node_beam -.->|"uses vectors"| node_embeddings
node_beam -.->|"reports diagnostics"| node_diagnostics
node_canonical -.->|"shares memory store"| node_banks
node_config -->|"configures runtime"| node_memory
node_importers -.->|"imports memories"| node_memory
node_sync -.->|"syncs instances"| node_memory
node_modelrefresh -->|"reads settings"| node_config
node_modelrefresh -->|"uses canonicalization"| node_content
node_embeddings -->|"identifies client"| node_useragent
node_doctor -->|"checks embeddings"| node_embeddings

click node_sdk "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/__init__.py"
click node_mcp "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/mcp_tools.py"
click node_cli "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/cli.py"
click node_hermes "https://github.com/mnemosyne-oss/mnemosyne/blob/main/integrations/hermes/src/mnemosyne_hermes/__init__.py"
click node_openwebui "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/integrations/openwebui_tool.py"
click node_openclaw "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/integrations/openclaw.py"
click node_vscode "https://github.com/mnemosyne-oss/mnemosyne/blob/main/integrations/vscode-mnemosyne/src/client.ts"
click node_obsidian "https://github.com/mnemosyne-oss/mnemosyne/blob/main/integrations/obsidian-mnemosyne/main.ts"
click node_extraction "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/extraction/client.py"
click node_writefilters "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/filters.py"
click node_memory "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/memory.py"
click node_batch "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/batch_tool.py"
click node_consolidation "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/veracity_consolidation.py"
click node_canonical "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/canonical.py"
click node_episodic "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/episodic_graph.py"
click node_beam "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/beam.py"
click node_embeddings "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/embeddings.py"
click node_triples "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/triples.py"
click node_annotations "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/annotations.py"
click node_banks "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/banks.py"
click node_journal "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/journal.py"
click node_config "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/config.py"
click node_importers "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/importers/__init__.py"
click node_sync "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/sync.py"
click node_diagnostics "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/recall_diagnostics.py"
click node_modelrefresh "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/model_refresh.py"
click node_useragent "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/user_agent.py"
click node_content "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/canonical.py"
click node_doctor "https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/diagnose.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_sdk,node_mcp,node_cli,node_hermes,node_openwebui,node_openclaw,node_vscode,node_obsidian,node_agent toneBlue
class node_extraction,node_writefilters,node_memory,node_batch,node_consolidation,node_canonical,node_episodic,node_content toneAmber
class node_beam,node_embeddings,node_triples,node_annotations toneMint
class node_banks,node_journal,node_config,node_importers,node_sync,node_diagnostics,node_modelrefresh,node_useragent,node_doctor toneRose
```

## Components

### Agent Interfaces

- [Python SDK](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/__init__.py): `mnemosyne/__init__.py`
- [MCP Tools](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/mcp_tools.py): `mnemosyne/mcp_tools.py`
- [Command Line](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/cli.py): `mnemosyne/cli.py`
- [Hermes Provider](https://github.com/mnemosyne-oss/mnemosyne/blob/main/integrations/hermes/src/mnemosyne_hermes/__init__.py): `integrations/hermes/src/mnemosyne_hermes/__init__.py`
- [OpenWebUI Bridge](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/integrations/openwebui_tool.py): `mnemosyne/integrations/openwebui_tool.py`
- [OpenClaw Provider](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/integrations/openclaw.py): `mnemosyne/integrations/openclaw.py`
- [VS Code Extension](https://github.com/mnemosyne-oss/mnemosyne/blob/main/integrations/vscode-mnemosyne/src/client.ts): `integrations/vscode-mnemosyne/src/client.ts`
- [Obsidian Plugin](https://github.com/mnemosyne-oss/mnemosyne/blob/main/integrations/obsidian-mnemosyne/main.ts): `integrations/obsidian-mnemosyne/main.ts`

### Memory Processing

- [Fact Extraction](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/extraction/client.py): `mnemosyne/extraction/client.py`
- [Write Filtering](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/filters.py): `mnemosyne/core/filters.py`
- [Memory API](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/memory.py): `mnemosyne/core/memory.py`
- [Batch Operations](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/batch_tool.py): `mnemosyne/batch_tool.py`
- [Veracity Consolidation](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/veracity_consolidation.py): `mnemosyne/core/veracity_consolidation.py`
- [Canonical Facts](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/canonical.py): `mnemosyne/core/canonical.py`
- [Episodic Graph](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/episodic_graph.py): `mnemosyne/core/episodic_graph.py`
- [Content Canonicalization](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/canonical.py): `mnemosyne/core/canonical.py`

### Recall and Retrieval

- [BEAM Recall](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/beam.py): `mnemosyne/core/beam.py`
- [Dense Embeddings](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/embeddings.py): `mnemosyne/core/embeddings.py`
- [Memory Triples](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/triples.py): `mnemosyne/core/triples.py`
- [Annotations](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/annotations.py): `mnemosyne/core/annotations.py`

### State and Operations

- [Memory Banks](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/banks.py): `mnemosyne/core/banks.py`
- [Journal](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/journal.py): `mnemosyne/core/journal.py`
- [Runtime Configuration](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/config.py): `mnemosyne/core/config.py`
- [Memory Importers](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/importers/__init__.py): `mnemosyne/core/importers/__init__.py`
- [Instance Sync](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/sync.py): `mnemosyne/core/sync.py`
- [Recall Diagnostics](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/recall_diagnostics.py): `mnemosyne/core/recall_diagnostics.py`
- [Model Refresh](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/model_refresh.py): `mnemosyne/core/model_refresh.py`
- [User and Agent Context](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/core/user_agent.py): `mnemosyne/core/user_agent.py`
- [Health Diagnostics](https://github.com/mnemosyne-oss/mnemosyne/blob/main/mnemosyne/diagnose.py): `mnemosyne/diagnose.py`

### Other components

- **Agent or User**

## Connections

- Agent or User → Python SDK: calls (evidence: `README.md`)
- Python SDK → Memory API: stores or recalls (evidence: `mnemosyne/__init__.py`)
- Agent or User → MCP Tools: uses (evidence: `README.md`)
- MCP Tools → Memory API: accesses memory
- Agent or User → Command Line: runs commands (evidence: `README.md`)
- Command Line → Memory API: stores or recalls
- Agent or User → Hermes Provider: uses provider (evidence: `README.md`)
- Hermes Provider → Memory API: accesses memory (evidence: `integrations/hermes/src/mnemosyne_hermes/__init__.py`)
- Agent or User → OpenWebUI Bridge: uses tool (evidence: `README.md`)
- OpenWebUI Bridge → Memory API: calls
- Agent or User → OpenClaw Provider: uses provider (evidence: `README.md`)
- Agent or User → VS Code Extension: uses extension
- Agent or User → Obsidian Plugin: uses plugin
- Memory API → Write Filtering: filters writes (evidence: `mnemosyne/core/memory.py`)
- Memory API → BEAM Recall: delegates recall (evidence: `mnemosyne/core/memory.py`)
- Memory API → Dense Embeddings: uses vectors (evidence: `mnemosyne/core/memory.py`)
- Memory API → Memory Banks: uses banks (evidence: `mnemosyne/core/memory.py`)
- Memory API → Journal: records changes (evidence: `mnemosyne/core/memory.py`)
- Memory API → Memory Triples: uses triples (evidence: `mnemosyne/core/memory.py`)
- Memory API → Annotations: uses annotations (evidence: `mnemosyne/core/memory.py`)
- Memory API → Content Canonicalization: uses canonicalization (evidence: `mnemosyne/core/memory.py`)
- Memory API → Episodic Graph: uses graph (evidence: `hermes_memory_provider/__init__.py`)
- Batch Operations → BEAM Recall: uses recall (evidence: `mnemosyne/batch_tool.py`)
- Batch Operations → Veracity Consolidation: uses consolidation (evidence: `mnemosyne/batch_tool.py`)
- BEAM Recall → Dense Embeddings: uses vectors
- BEAM Recall → Recall Diagnostics: reports diagnostics
- Canonical Facts → Memory Banks: shares memory store
- Runtime Configuration → Memory API: configures runtime (evidence: `mnemosyne/core/memory.py`)
- Memory Importers → Memory API: imports memories
- Instance Sync → Memory API: syncs instances
- Model Refresh → Runtime Configuration: reads settings (evidence: `mnemosyne/core/model_refresh.py`)
- Model Refresh → Content Canonicalization: uses canonicalization (evidence: `mnemosyne/core/model_refresh.py`)
- Dense Embeddings → User and Agent Context: identifies client (evidence: `mnemosyne/core/embeddings.py`)
- Health Diagnostics → Dense Embeddings: checks embeddings