# dkshbyte/mindbaton architecture

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

- Interactive diagram: https://gitdiagram.com/dkshbyte/mindbaton
- Repository: https://github.com/dkshbyte/mindbaton

## Overview

Mindbaton is a private, local-first shared memory service for conversations across AI clients. Users capture chats through the browser extension or connect agents and import existing notes; the server processes them into a searchable memory graph, which clients can query or use to create hand-off packs. The README also documents multi-account privacy, offline semantic search, optional model and provider assistance, and data export. Several server internals and UI routes were not sampled, so those subsystem links are documented or omitted rather than inferred from filenames.

Main entry points: [`server.py`](https://github.com/dkshbyte/mindbaton/blob/main/server.py) (HTTP server), [`extension/content.js`](https://github.com/dkshbyte/mindbaton/blob/main/extension/content.js) (Browser extension), [`mindbaton.py`](https://github.com/dkshbyte/mindbaton/blob/main/mindbaton.py) (Agent connector), [`mcp_stdio.py`](https://github.com/dkshbyte/mindbaton/blob/main/mcp_stdio.py) (MCP bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Capture and connections"]
  node_extension["Browser extension<br/>[content.js]"]
  node_cli["Agent connector<br/>[mindbaton.py]"]
  node_mcp["MCP bridge<br/>[mcp_stdio.py]"]
  node_importer["Memory importer<br/>[import_memories.py]"]
end

subgraph group_memory["Memory processing"]
  node_sessions["Live sessions<br/>[live.py]"]
  node_brain["Fact extraction<br/>[brain.py]"]
  node_learner["Rule-gap learner<br/>[learn.py]"]
  node_model["Optional reader<br/>[deep.py]"]
  node_semantics["Semantic vectors<br/>[sense.py]"]
end

subgraph group_service["Memory service"]
  node_server["HTTP server<br/>[server.py]"]
  node_memory_db[("Memory graph<br/>[server.py]")]
  node_recall["Recall and answers<br/>[server.py]"]
  node_ai["Optional AI providers<br/>[ai.py]"]
end

subgraph group_clients["AI experiences"]
  node_handoff["Handoff packs<br/>[handoff.py]"]
  node_web_app["Web app<br/>[index.html]"]
end

subgraph group_operations["Account and portability"]
  node_accounts[("Private accounts<br/>[server.py]")]
  node_setup["Setup and device linking<br/>[mindbaton.py]"]
end

node_person(("User"))
node_ai_clients(("AI clients"))

node_person -->|"captures chats"| node_extension
node_extension -->|"sends captures"| node_server
node_ai_clients -->|"connects agents"| node_cli
node_cli -->|"sends memories"| node_server
node_ai_clients -->|"uses MCP"| node_mcp
node_mcp -->|"bridges requests"| node_server
node_person -->|"imports notes"| node_importer
node_importer -->|"posts memories"| node_server
node_server -->|"records sessions"| node_sessions
node_server -->|"processes captures"| node_brain
node_brain -->|"asks when needed"| node_learner
node_server -->|"requests reading"| node_model
node_server -->|"uses vectors"| node_semantics
node_server -->|"stores graph"| node_memory_db
node_server -->|"routes recall"| node_recall
node_recall -->|"reads memories"| node_memory_db
node_ai_clients -->|"asks memory"| node_server
node_server -.->|"requests answers"| node_ai
node_server -->|"builds handoffs"| node_handoff
node_server -->|"serves interface"| node_web_app
node_person -->|"manages memory"| node_web_app
node_server -->|"isolates accounts"| node_accounts
node_person -->|"links devices"| node_setup
node_setup -->|"configures connection"| node_server

click node_extension "https://github.com/dkshbyte/mindbaton/blob/main/extension/content.js"
click node_cli "https://github.com/dkshbyte/mindbaton/blob/main/mindbaton.py"
click node_mcp "https://github.com/dkshbyte/mindbaton/blob/main/mcp_stdio.py"
click node_importer "https://github.com/dkshbyte/mindbaton/blob/main/import_memories.py"
click node_server "https://github.com/dkshbyte/mindbaton/blob/main/server.py"
click node_sessions "https://github.com/dkshbyte/mindbaton/blob/main/live.py"
click node_brain "https://github.com/dkshbyte/mindbaton/blob/main/brain.py"
click node_learner "https://github.com/dkshbyte/mindbaton/blob/main/learn.py"
click node_model "https://github.com/dkshbyte/mindbaton/blob/main/deep.py"
click node_semantics "https://github.com/dkshbyte/mindbaton/blob/main/sense.py"
click node_memory_db "https://github.com/dkshbyte/mindbaton/blob/main/server.py"
click node_recall "https://github.com/dkshbyte/mindbaton/blob/main/server.py"
click node_ai "https://github.com/dkshbyte/mindbaton/blob/main/ai.py"
click node_handoff "https://github.com/dkshbyte/mindbaton/blob/main/handoff.py"
click node_web_app "https://github.com/dkshbyte/mindbaton/blob/main/index.html"
click node_accounts "https://github.com/dkshbyte/mindbaton/blob/main/server.py"
click node_setup "https://github.com/dkshbyte/mindbaton/blob/main/mindbaton.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_extension,node_cli,node_mcp,node_importer,node_person,node_ai_clients toneBlue
class node_sessions,node_brain,node_learner,node_model,node_semantics toneAmber
class node_server,node_memory_db,node_recall,node_ai toneMint
class node_handoff,node_web_app toneRose
class node_accounts,node_setup toneIndigo
```

## Components

### Capture and connections

- [Browser extension](https://github.com/dkshbyte/mindbaton/blob/main/extension/content.js): `extension/content.js`
- [Agent connector](https://github.com/dkshbyte/mindbaton/blob/main/mindbaton.py): `mindbaton.py`
- [MCP bridge](https://github.com/dkshbyte/mindbaton/blob/main/mcp_stdio.py): `mcp_stdio.py`
- [Memory importer](https://github.com/dkshbyte/mindbaton/blob/main/import_memories.py): `import_memories.py`

### Memory processing

- [Live sessions](https://github.com/dkshbyte/mindbaton/blob/main/live.py): `live.py`
- [Fact extraction](https://github.com/dkshbyte/mindbaton/blob/main/brain.py): `brain.py`
- [Rule-gap learner](https://github.com/dkshbyte/mindbaton/blob/main/learn.py): `learn.py`
- [Optional reader](https://github.com/dkshbyte/mindbaton/blob/main/deep.py): `deep.py`
- [Semantic vectors](https://github.com/dkshbyte/mindbaton/blob/main/sense.py): `sense.py`

### Memory service

- [HTTP server](https://github.com/dkshbyte/mindbaton/blob/main/server.py): `server.py`
- [Memory graph](https://github.com/dkshbyte/mindbaton/blob/main/server.py): `server.py`
- [Recall and answers](https://github.com/dkshbyte/mindbaton/blob/main/server.py): `server.py`
- [Optional AI providers](https://github.com/dkshbyte/mindbaton/blob/main/ai.py): `ai.py`

### AI experiences

- [Handoff packs](https://github.com/dkshbyte/mindbaton/blob/main/handoff.py): `handoff.py`
- [Web app](https://github.com/dkshbyte/mindbaton/blob/main/index.html): `index.html`

### Account and portability

- [Private accounts](https://github.com/dkshbyte/mindbaton/blob/main/server.py): `server.py`
- [Setup and device linking](https://github.com/dkshbyte/mindbaton/blob/main/mindbaton.py): `mindbaton.py`

### Other components

- **User**
- **AI clients**

## Connections

- User → Browser extension: captures chats (evidence: `README.md`)
- Browser extension → HTTP server: sends captures (evidence: `README.md`)
- AI clients → Agent connector: connects agents (evidence: `README.md`)
- Agent connector → HTTP server: sends memories (evidence: `mindbaton.py`)
- AI clients → MCP bridge: uses MCP (evidence: `README.md`)
- MCP bridge → HTTP server: bridges requests (evidence: `README.md`)
- User → Memory importer: imports notes (evidence: `README.md`)
- Memory importer → HTTP server: posts memories (evidence: `import_memories.py`)
- HTTP server → Live sessions: records sessions (evidence: `server.py`)
- HTTP server → Fact extraction: processes captures (evidence: `server.py`)
- Fact extraction → Rule-gap learner: asks when needed (evidence: `brain.py`)
- HTTP server → Optional reader: requests reading (evidence: `server.py`)
- HTTP server → Semantic vectors: uses vectors (evidence: `server.py`)
- HTTP server → Memory graph: stores graph (evidence: `server.py`)
- HTTP server → Recall and answers: routes recall (evidence: `server.py`)
- Recall and answers → Memory graph: reads memories (evidence: `server.py`)
- AI clients → HTTP server: asks memory (evidence: `README.md`)
- HTTP server → Optional AI providers: requests answers (evidence: `server.py`)
- HTTP server → Handoff packs: builds handoffs (evidence: `live.py`)
- HTTP server → Web app: serves interface (evidence: `README.md`)
- User → Web app: manages memory (evidence: `README.md`)
- HTTP server → Private accounts: isolates accounts (evidence: `README.md`)
- User → Setup and device linking: links devices (evidence: `README.md`)
- Setup and device linking → HTTP server: configures connection (evidence: `mindbaton.py`)
