# oleksiijko/pmb architecture

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

- Interactive diagram: https://gitdiagram.com/oleksiijko/pmb
- Repository: https://github.com/oleksiijko/pmb

## Overview

PMB is local-first persistent memory for AI coding agents. The main loop is agent activity → automatic hook capture → durable workspace storage; later, the agent requests context through MCP, which retrieves and returns relevant memories. Separate capabilities include project/PDF indexing, graph and timeline visualization, session restoration, and memory maintenance. The README documents these product areas; sampled source confirms parts of MCP serving, hybrid search, dashboard handling, and session tracking, so links for unsampled implementations are limited to documented behavior.

Main entry points: [`src/pmb/core/engine`](https://github.com/oleksiijko/pmb/tree/main/src/pmb/core/engine) (Memory engine), [`src/pmb/cli/main.py`](https://github.com/oleksiijko/pmb/blob/main/src/pmb/cli/main.py) (PMB CLI), [`src/pmb/hooks`](https://github.com/oleksiijko/pmb/tree/main/src/pmb/hooks) (Agent hooks), [`src/pmb/dashboard/server.py`](https://github.com/oleksiijko/pmb/blob/main/src/pmb/dashboard/server.py) (Local dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_hooks["Agent hooks"]
  node_mcp["MCP server<br/>[server.py]"]
  node_cli["PMB CLI<br/>[main.py]"]
end

subgraph group_memory["Memory runtime"]
  node_engine["Memory engine"]
  node_sqlite[("SQLite workspace<br/>[sqlite_helper.py]")]
  node_workspace["Workspace management<br/>[workspace.py]"]
  node_search["Hybrid search<br/>[search.py]"]
  node_embed["Embedding queue<br/>[embed_queue.py]"]
end

subgraph group_knowledge["Knowledge processing"]
  node_graph[("Entity graph<br/>[store.py]")]
  node_reasoning["Recall reasoning<br/>[router.py]"]
  node_ingest["Project and PDF ingest"]
  node_signals["Activity signals"]
  node_session["Session tracking<br/>[session.py]"]
  node_restore["Session restore<br/>[session_restore.py]"]
end

subgraph group_workspace["Workspace operations"]
  node_health["Memory health"]
  node_maintenance["Memory maintenance"]
  node_snapshots["Verified snapshots<br/>[snapshots.py]"]
end

subgraph group_visibility["Memory visibility"]
  node_dashboard["Local dashboard<br/>[server.py]"]
  node_viz["Graph visualization<br/>[viz.py]"]
end

node_agent(("Coding agent"))

node_agent -->|"triggers capture"| node_hooks
node_hooks -->|"records activity"| node_engine
node_agent -->|"requests memory"| node_mcp
node_mcp -->|"dispatches tools"| node_engine
node_engine -->|"reads and writes"| node_sqlite
node_engine -->|"retrieves memories"| node_search
node_search -->|"queues embeddings"| node_embed
node_engine -->|"routes recall"| node_reasoning
node_engine -->|"updates entities"| node_graph
node_cli -->|"indexes sources"| node_ingest
node_ingest -->|"stores extracted content"| node_engine
node_hooks -->|"collects context"| node_signals
node_engine -->|"tracks sessions"| node_session
node_restore -->|"builds session brief"| node_engine
node_cli -->|"checks memory"| node_health
node_cli -->|"runs maintenance"| node_maintenance
node_cli -->|"manages backups"| node_snapshots
node_cli -->|"opens dashboard"| node_dashboard
node_dashboard -->|"reads workspace"| node_engine
node_dashboard -->|"renders graph"| node_viz

click node_hooks "https://github.com/oleksiijko/pmb/tree/main/src/pmb/hooks"
click node_mcp "https://github.com/oleksiijko/pmb/blob/main/src/pmb/mcp/server.py"
click node_cli "https://github.com/oleksiijko/pmb/blob/main/src/pmb/cli/main.py"
click node_engine "https://github.com/oleksiijko/pmb/tree/main/src/pmb/core/engine"
click node_sqlite "https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/sqlite_helper.py"
click node_workspace "https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/workspace.py"
click node_search "https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/search.py"
click node_embed "https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/embed_queue.py"
click node_graph "https://github.com/oleksiijko/pmb/blob/main/src/pmb/graph/store.py"
click node_reasoning "https://github.com/oleksiijko/pmb/blob/main/src/pmb/reasoning/router.py"
click node_ingest "https://github.com/oleksiijko/pmb/tree/main/src/pmb/ingest"
click node_signals "https://github.com/oleksiijko/pmb/tree/main/src/pmb/signals"
click node_session "https://github.com/oleksiijko/pmb/blob/main/src/pmb/signals/session.py"
click node_restore "https://github.com/oleksiijko/pmb/blob/main/src/pmb/hooks/session_restore.py"
click node_health "https://github.com/oleksiijko/pmb/tree/main/src/pmb/health"
click node_maintenance "https://github.com/oleksiijko/pmb/tree/main/src/pmb/maintenance"
click node_snapshots "https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/snapshots.py"
click node_dashboard "https://github.com/oleksiijko/pmb/blob/main/src/pmb/dashboard/server.py"
click node_viz "https://github.com/oleksiijko/pmb/blob/main/src/pmb/dashboard/viz.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_hooks,node_mcp,node_cli toneBlue
class node_engine,node_sqlite,node_workspace,node_search,node_embed toneAmber
class node_graph,node_reasoning,node_ingest,node_signals,node_session,node_restore toneMint
class node_health,node_maintenance,node_snapshots toneRose
class node_dashboard,node_viz,node_agent toneIndigo
```

## Components

### Agent interfaces

- [Agent hooks](https://github.com/oleksiijko/pmb/tree/main/src/pmb/hooks): `src/pmb/hooks`
- [MCP server](https://github.com/oleksiijko/pmb/blob/main/src/pmb/mcp/server.py): `src/pmb/mcp/server.py`
- [PMB CLI](https://github.com/oleksiijko/pmb/blob/main/src/pmb/cli/main.py): `src/pmb/cli/main.py`

### Memory runtime

- [Memory engine](https://github.com/oleksiijko/pmb/tree/main/src/pmb/core/engine): `src/pmb/core/engine`
- [SQLite workspace](https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/sqlite_helper.py): `src/pmb/core/sqlite_helper.py`
- [Workspace management](https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/workspace.py): `src/pmb/core/workspace.py`
- [Hybrid search](https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/search.py): `src/pmb/core/search.py`
- [Embedding queue](https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/embed_queue.py): `src/pmb/core/embed_queue.py`

### Knowledge processing

- [Entity graph](https://github.com/oleksiijko/pmb/blob/main/src/pmb/graph/store.py): `src/pmb/graph/store.py`
- [Recall reasoning](https://github.com/oleksiijko/pmb/blob/main/src/pmb/reasoning/router.py): `src/pmb/reasoning/router.py`
- [Project and PDF ingest](https://github.com/oleksiijko/pmb/tree/main/src/pmb/ingest): `src/pmb/ingest`
- [Activity signals](https://github.com/oleksiijko/pmb/tree/main/src/pmb/signals): `src/pmb/signals`
- [Session tracking](https://github.com/oleksiijko/pmb/blob/main/src/pmb/signals/session.py): `src/pmb/signals/session.py`
- [Session restore](https://github.com/oleksiijko/pmb/blob/main/src/pmb/hooks/session_restore.py): `src/pmb/hooks/session_restore.py`

### Workspace operations

- [Memory health](https://github.com/oleksiijko/pmb/tree/main/src/pmb/health): `src/pmb/health`
- [Memory maintenance](https://github.com/oleksiijko/pmb/tree/main/src/pmb/maintenance): `src/pmb/maintenance`
- [Verified snapshots](https://github.com/oleksiijko/pmb/blob/main/src/pmb/core/snapshots.py): `src/pmb/core/snapshots.py`

### Memory visibility

- [Local dashboard](https://github.com/oleksiijko/pmb/blob/main/src/pmb/dashboard/server.py): `src/pmb/dashboard/server.py`
- [Graph visualization](https://github.com/oleksiijko/pmb/blob/main/src/pmb/dashboard/viz.py): `src/pmb/dashboard/viz.py`

### Other components

- **Coding agent**

## Connections

- Coding agent → Agent hooks: triggers capture
- Agent hooks → Memory engine: records activity
- Coding agent → MCP server: requests memory
- MCP server → Memory engine: dispatches tools
- Memory engine → SQLite workspace: reads and writes
- Memory engine → Hybrid search: retrieves memories
- Hybrid search → Embedding queue: queues embeddings
- Memory engine → Recall reasoning: routes recall
- Memory engine → Entity graph: updates entities
- PMB CLI → Project and PDF ingest: indexes sources
- Project and PDF ingest → Memory engine: stores extracted content
- Agent hooks → Activity signals: collects context
- Memory engine → Session tracking: tracks sessions
- Session restore → Memory engine: builds session brief
- PMB CLI → Memory health: checks memory
- PMB CLI → Memory maintenance: runs maintenance
- PMB CLI → Verified snapshots: manages backups
- PMB CLI → Local dashboard: opens dashboard
- Local dashboard → Memory engine: reads workspace
- Local dashboard → Graph visualization: renders graph