# star-ga/mind-mem architecture

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

- Interactive diagram: https://gitdiagram.com/star-ga/mind-mem
- Repository: https://github.com/star-ga/mind-mem

## Overview

MIND-Mem is a local-first, governed memory substrate for AI agents. Agents connect through MCP or REST, submit proposed changes for review and approval, and retrieve ranked memories from an admitted corpus. Applied changes are persisted and hash-anchored for audit and replay; import, graph recall, drift scanning, and browser consoles extend the core workflow. The README documents these capabilities, but the sampled source is partial, so links for unsampled subsystems are limited to documented behavior rather than inferred internal calls.

Main entry points: [`src/mind_mem/block_store.py`](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py) (Memory blocks), [`src/mind_mem/recall.py`](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py) (Ranked recall), [`src/mind_mem/api/rest.py`](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/api/rest.py) (REST API), [`src/mind_mem/governance_gate.py`](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py) (Governance gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcp_tools["MCP tools"]
  node_rest["REST API<br/>[rest.py]"]
  node_web_console["Web console<br/>[page.tsx]"]
  node_web_proxy["REST proxy<br/>[route.ts]"]
  node_web_view["Memory viewer<br/>[app.js]"]
  node_sdk_clients["SDK clients<br/>[client.ts]"]
end

subgraph group_memory["Memory lifecycle"]
  node_ingest["Ingestion pipeline"]
  node_import_engine["Import engine<br/>[engine.py]"]
  node_blocks[("Memory blocks<br/>[block_store.py]")]
  node_postgres[("Postgres backend")]
end

subgraph group_recall["Recall and analysis"]
  node_recall["Ranked recall<br/>[recall.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybrid_recall.py]"]
  node_graph_recall["Graph recall<br/>[graph_recall.py]"]
end

subgraph group_governance["Governance and evidence"]
  node_proposal_apply["Proposal apply<br/>[apply_engine.py]"]
  node_gate["Governance gate<br/>[governance_gate.py]"]
  node_audit["Audit chain<br/>[audit_chain.py]"]
end

subgraph group_operations["Operations and clients"]
  node_pipeline_hash["Pipeline freshness<br/>[pipeline_hash.py]"]
end

node_agent(("AI agent"))
node_operator(("Workspace operator"))

node_agent -->|"connects"| node_mcp
node_agent -->|"requests"| node_rest
node_mcp -->|"registers tools"| node_mcp_tools
node_mcp_tools -->|"serves recall"| node_recall
node_operator -->|"approves changes"| node_proposal_apply
node_proposal_apply -->|"checks writes"| node_gate
node_gate -->|"admits writes"| node_blocks
node_proposal_apply -->|"records apply"| node_audit
node_ingest -->|"submits writes"| node_gate
node_ingest -->|"writes blocks"| node_blocks
node_import_engine -->|"imports blocks"| node_blocks
node_recall -->|"uses retrieval"| node_hybrid
node_recall -->|"reads corpus"| node_blocks
node_graph_recall -->|"reads memory"| node_blocks
node_operator -->|"checks freshness"| node_pipeline_hash
node_pipeline_hash -->|"admits restamps"| node_gate
node_web_console -->|"sends requests"| node_web_proxy
node_web_proxy -->|"forwards requests"| node_rest
node_web_view -->|"searches memory"| node_recall
node_sdk_clients -->|"calls endpoints"| node_rest
node_rest -->|"serves recall"| node_recall
node_postgres -.->|"optional backend"| node_blocks

click node_mcp "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py"
click node_mcp_tools "https://github.com/star-ga/mind-mem/tree/main/src/mind_mem/mcp/tools"
click node_rest "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/api/rest.py"
click node_web_console "https://github.com/star-ga/mind-mem/blob/main/web/app/console/page.tsx"
click node_web_proxy "https://github.com/star-ga/mind-mem/blob/main/web/app/v1/%5B...path%5D/route.ts"
click node_ingest "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/ingestion_pipeline.py"
click node_import_engine "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/importers/engine.py"
click node_proposal_apply "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py"
click node_gate "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py"
click node_audit "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py"
click node_blocks "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py"
click node_recall "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py"
click node_hybrid "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py"
click node_graph_recall "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_recall.py"
click node_pipeline_hash "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/pipeline_hash.py"
click node_web_view "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/viewer_static/app.js"
click node_sdk_clients "https://github.com/star-ga/mind-mem/blob/main/sdk/js/src/client.ts"
click node_postgres "https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store_postgres.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_mcp_tools,node_rest,node_web_console,node_web_proxy,node_web_view,node_sdk_clients toneBlue
class node_ingest,node_import_engine,node_blocks,node_postgres toneAmber
class node_recall,node_hybrid,node_graph_recall toneMint
class node_proposal_apply,node_gate,node_audit toneRose
class node_pipeline_hash,node_agent,node_operator toneIndigo
```

## Components

### Agent interfaces

- [MCP server](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py): `src/mind_mem/mcp/server.py`
- [MCP tools](https://github.com/star-ga/mind-mem/tree/main/src/mind_mem/mcp/tools): `src/mind_mem/mcp/tools`
- [REST API](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/api/rest.py): `src/mind_mem/api/rest.py`
- [Web console](https://github.com/star-ga/mind-mem/blob/main/web/app/console/page.tsx): `web/app/console/page.tsx`
- [REST proxy](https://github.com/star-ga/mind-mem/blob/main/web/app/v1/%5B...path%5D/route.ts): `web/app/v1/[...path]/route.ts`
- [Memory viewer](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/viewer_static/app.js): `src/mind_mem/viewer_static/app.js`
- [SDK clients](https://github.com/star-ga/mind-mem/blob/main/sdk/js/src/client.ts): `sdk/js/src/client.ts`

### Memory lifecycle

- [Ingestion pipeline](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/ingestion_pipeline.py): `src/mind_mem/ingestion_pipeline.py`
- [Import engine](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/importers/engine.py): `src/mind_mem/importers/engine.py`
- [Memory blocks](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py): `src/mind_mem/block_store.py`
- [Postgres backend](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store_postgres.py): `src/mind_mem/block_store_postgres.py`

### Recall and analysis

- [Ranked recall](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py): `src/mind_mem/recall.py`
- [Hybrid retrieval](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py): `src/mind_mem/hybrid_recall.py`
- [Graph recall](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_recall.py): `src/mind_mem/graph_recall.py`

### Governance and evidence

- [Proposal apply](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py): `src/mind_mem/apply_engine.py`
- [Governance gate](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py): `src/mind_mem/governance_gate.py`
- [Audit chain](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py): `src/mind_mem/audit_chain.py`

### Operations and clients

- [Pipeline freshness](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/pipeline_hash.py): `src/mind_mem/pipeline_hash.py`

### Other components

- **AI agent**
- **Workspace operator**

## Connections

- AI agent → MCP server: connects
- AI agent → REST API: requests
- MCP server → MCP tools: registers tools
- MCP tools → Ranked recall: serves recall
- Workspace operator → Proposal apply: approves changes
- Proposal apply → Governance gate: checks writes
- Governance gate → Memory blocks: admits writes
- Proposal apply → Audit chain: records apply
- Ingestion pipeline → Governance gate: submits writes
- Ingestion pipeline → Memory blocks: writes blocks
- Import engine → Memory blocks: imports blocks
- Ranked recall → Hybrid retrieval: uses retrieval
- Ranked recall → Memory blocks: reads corpus
- Graph recall → Memory blocks: reads memory
- Workspace operator → Pipeline freshness: checks freshness
- Pipeline freshness → Governance gate: admits restamps
- Web console → REST proxy: sends requests
- REST proxy → REST API: forwards requests
- Memory viewer → Ranked recall: searches memory
- SDK clients → REST API: calls endpoints
- REST API → Ranked recall: serves recall
- Postgres backend → Memory blocks: optional backend