# slow-stack/mneme architecture

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

## Overview

dsh-mneme is a cross-session memory plugin for DeepSeek Harness, with an optional stdio MCP interface. The main loop saves conversation-derived memories, persists them, recalls relevant items through hybrid search, and injects them into later sessions; idle maintenance consolidates and audits stored memories. The README also documents Markdown synchronization, entity relationships, scope controls, and a web workbench. Edges follow documented behavior and sampled wiring; unsampled subsystem internals are represented without speculative call chains.

Main entry points: [`dsh-mneme/lib/service.js`](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/service.js) (Memory service), [`dsh-mneme/lib/index.js`](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/index.js) (Plugin bootstrap), [`dsh-mneme/lib/api.js`](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/api.js) (External API), [`dsh-mneme/lib/dream/sleep.js`](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/dream/sleep.js) (Sleep maintenance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Plugin interfaces"]
  node_plugin["Plugin bootstrap<br/>[index.js]"]
  node_tools["Memory tools<br/>[tools.js]"]
  node_api["External API<br/>[api.js]"]
  node_mcp["MCP server<br/>[mneme-mcp.mjs]"]
  node_client["Web workbench<br/>[client.js]"]
end

subgraph group_memory["Memory lifecycle"]
  node_service["Memory service<br/>[service.js]"]
  node_quality["Write quality<br/>[quality-filter.js]"]
  node_entities["Entity extraction<br/>[extractor.js]"]
end

subgraph group_recall["Recall and injection"]
  node_injection["Context injection<br/>[inject.js]"]
  node_embedding["Embedding providers<br/>[embedding.js]"]
  node_localembed["Local embedding<br/>[local-embedder.js]"]
  node_vector["Vector index<br/>[vector-index.js]"]
  node_bm25["BM25 search<br/>[bm25.js]"]
end

subgraph group_maintenance["Consolidation and audit"]
  node_dream["AutoDream<br/>[dream.js]"]
  node_sleep["Sleep maintenance<br/>[sleep.js]"]
  node_entities_graph["Entity relationships<br/>[extractor.js]"]
end

subgraph group_state["Persistence and configuration"]
  node_store[("SQLite store<br/>[store.js]")]
  node_mirror["Markdown mirror<br/>[mirror.js]"]
  node_documents["Document index<br/>[document-index.js]"]
  node_settings["Settings and scope<br/>[settings.js]"]
end

node_user(("User"))
node_dsh(("DSH host"))
node_mcpclient(("MCP client"))
node_embedservice["Embedding endpoint"]

node_user -->|"starts conversation"| node_dsh
node_dsh -->|"loads plugin"| node_plugin
node_plugin -->|"registers tools"| node_tools
node_tools -->|"invoke memory actions"| node_service
node_service -->|"checks writes"| node_quality
node_service -->|"reads and writes"| node_store
node_service -->|"synchronizes memories"| node_mirror
node_service -->|"extracts entities"| node_entities
node_service -->|"requests vectors"| node_embedding
node_service -.->|"uses local vectors"| node_localembed
node_embedding -.->|"requests embeddings"| node_embedservice
node_service -->|"searches vectors"| node_vector
node_service -->|"searches keywords"| node_bm25
node_plugin -->|"registers injection"| node_injection
node_injection -->|"recalls memories"| node_service
node_plugin -->|"wires consolidation"| node_dream
node_plugin -->|"schedules idle maintenance"| node_sleep
node_sleep -->|"maintains memories"| node_service
node_sleep -->|"records audit receipts"| node_store
node_plugin -->|"initializes document index"| node_documents
node_user -->|"manages memory"| node_client
node_client -->|"uses plugin API"| node_api
node_mcpclient -->|"invokes memory tools"| node_mcp
node_mcp -->|"sends authenticated requests"| node_api
node_plugin -->|"registers API"| node_api
node_api -->|"handles memory requests"| node_service
node_entities -->|"stores relationships"| node_store
node_settings -->|"configures startup"| node_plugin

click node_plugin "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/index.js"
click node_tools "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/tools.js"
click node_api "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/api.js"
click node_mcp "https://github.com/slow-stack/mneme/blob/main/mcp/bin/mneme-mcp.mjs"
click node_client "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/client.js"
click node_service "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/service.js"
click node_quality "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/quality-filter.js"
click node_entities "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/entities/extractor.js"
click node_injection "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/inject.js"
click node_embedding "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/embedding.js"
click node_localembed "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/local-embedder.js"
click node_vector "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/vector-index.js"
click node_bm25 "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/search/bm25.js"
click node_dream "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/dream.js"
click node_sleep "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/dream/sleep.js"
click node_entities_graph "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/entities/extractor.js"
click node_store "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/store.js"
click node_mirror "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/mirror.js"
click node_documents "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/document-index.js"
click node_settings "https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/settings.js"

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_plugin,node_tools,node_api,node_mcp,node_client,node_user,node_mcpclient toneBlue
class node_service,node_quality,node_entities toneAmber
class node_injection,node_embedding,node_localembed,node_vector,node_bm25 toneMint
class node_dream,node_sleep,node_entities_graph toneRose
class node_store,node_mirror,node_documents,node_settings,node_dsh,node_embedservice toneIndigo
```

## Components

### Plugin interfaces

- [Plugin bootstrap](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/index.js): `dsh-mneme/lib/index.js`
- [Memory tools](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/tools.js): `dsh-mneme/lib/tools.js`
- [External API](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/api.js): `dsh-mneme/lib/api.js`
- [MCP server](https://github.com/slow-stack/mneme/blob/main/mcp/bin/mneme-mcp.mjs): `mcp/bin/mneme-mcp.mjs`
- [Web workbench](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/client.js): `dsh-mneme/lib/client.js`

### Memory lifecycle

- [Memory service](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/service.js): `dsh-mneme/lib/service.js`
- [Write quality](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/quality-filter.js): `dsh-mneme/lib/quality-filter.js`
- [Entity extraction](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/entities/extractor.js): `dsh-mneme/lib/entities/extractor.js`

### Recall and injection

- [Context injection](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/inject.js): `dsh-mneme/lib/inject.js`
- [Embedding providers](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/embedding.js): `dsh-mneme/lib/embedding.js`
- [Local embedding](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/local-embedder.js): `dsh-mneme/lib/local-embedder.js`
- [Vector index](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/vector-index.js): `dsh-mneme/lib/vector-index.js`
- [BM25 search](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/search/bm25.js): `dsh-mneme/lib/search/bm25.js`

### Consolidation and audit

- [AutoDream](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/dream.js): `dsh-mneme/lib/dream.js`
- [Sleep maintenance](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/dream/sleep.js): `dsh-mneme/lib/dream/sleep.js`
- [Entity relationships](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/entities/extractor.js): `dsh-mneme/lib/entities/extractor.js`

### Persistence and configuration

- [SQLite store](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/store.js): `dsh-mneme/lib/store.js`
- [Markdown mirror](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/mirror.js): `dsh-mneme/lib/mirror.js`
- [Document index](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/document-index.js): `dsh-mneme/lib/document-index.js`
- [Settings and scope](https://github.com/slow-stack/mneme/blob/main/dsh-mneme/lib/settings.js): `dsh-mneme/lib/settings.js`

### Other components

- **User**
- **DSH host**
- **MCP client**
- **Embedding endpoint**

## Connections

- User → DSH host: starts conversation
- DSH host → Plugin bootstrap: loads plugin
- Plugin bootstrap → Memory tools: registers tools
- Memory tools → Memory service: invoke memory actions
- Memory service → Write quality: checks writes
- Memory service → SQLite store: reads and writes
- Memory service → Markdown mirror: synchronizes memories
- Memory service → Entity extraction: extracts entities
- Memory service → Embedding providers: requests vectors
- Memory service → Local embedding: uses local vectors
- Embedding providers → Embedding endpoint: requests embeddings
- Memory service → Vector index: searches vectors
- Memory service → BM25 search: searches keywords
- Plugin bootstrap → Context injection: registers injection
- Context injection → Memory service: recalls memories
- Plugin bootstrap → AutoDream: wires consolidation
- Plugin bootstrap → Sleep maintenance: schedules idle maintenance
- Sleep maintenance → Memory service: maintains memories
- Sleep maintenance → SQLite store: records audit receipts
- Plugin bootstrap → Document index: initializes document index
- User → Web workbench: manages memory
- Web workbench → External API: uses plugin API
- MCP client → MCP server: invokes memory tools
- MCP server → External API: sends authenticated requests
- Plugin bootstrap → External API: registers API
- External API → Memory service: handles memory requests
- Entity extraction → SQLite store: stores relationships
- Settings and scope → Plugin bootstrap: configures startup