---
created: 2026-08-03 15:42
modified: 2026-08-03 15:45
type: note
tags:
  - ai
  - memory
  - architecture
aliases: []
---
# [[Ai memory management]]

## Architecture Map

```
┌──────────────────────────────────────────────────────────────────────┐
│                    AI MEMORY & CODE INTELLIGENCE                      │
│                                                                      │
│   ┌────────────┐          ┌───────────────┐                          │
│   │  OmniRoute │          │    Langfuse   │                          │
│   │  (.13:20129)         │   (.13:3001)   │                          │
│   │            │          │               │                          │
│   │ LLM proxy  │────────▶│ Observability │                          │
│   │ Combo      │  traces  │ Traces, evals │                          │
│   │ routing    │          │ cost tracking │                          │
│   └────────────┘          └───────────────┘                          │
│                                                                      │
│ ┌─────────────────── SESSION LAYER ──────────────────────┐          │
│ │                                                        │          │
│ │  ┌────────────┐  ┌──────────┐  ┌────────────────┐     │          │
│ │  │  Headroom  │  │  Engram  │  │  pi-memctx     │     │          │
│ │  │ (.13:8787) │  │(.13:7437)│  │  (pi ext)      │     │          │
│ │  │            │  │          │  │                │     │          │
│ │  │ Context    │  │ Session  │  │ Memory gateway │     │          │
│ │  │ compression│  │ journal  │  │ pack search    │     │          │
│ │  │ 60-95%     │  │ capture  │  │ in-session     │     │          │
│ │  │ reduction  │  │ recovery │  │ recall         │     │          │
│ │  └────────────┘  └────┬─────┘  └────────────────┘     │          │
│ │                       │                                │          │
│ │                 ┌─────▼──────┐                         │          │
│ │                 │ gentle-    │                         │          │
│ │                 │ engram     │                         │          │
│ │                 │ (pi ext)   │                         │          │
│ │                 │ ENGRAM_URL │                         │          │
│ │                 │ bridge     │                         │          │
│ │                 └────────────┘                         │          │
│ └────────────────────────────────────────────────────────┘          │
│                                                                      │
│ ┌─────────────────── CODE LAYER ─────────────────────────┐          │
│ │                                                        │          │
│ │  ┌──────────────────┐    ┌──────────────────────┐      │          │
│ │  │ codebase-memory  │    │  code-review-graph   │      │          │
│ │  │ -mcp             │    │  v2.3.7              │      │          │
│ │  │ v0.9.0           │    │                      │      │          │
│ │  │                  │    │  Per-project graphs  │      │          │
│ │  │ Machine-wide     │    │  .code-review-graph/ │      │          │
│ │  │ Tree-sitter AST  │    │  graph.db per repo  │      │          │
│ │  │ Agent learnings  │    │  28+ MCP tools      │      │          │
│ │  │ across projects  │    │  Blast radius       │      │          │
│ │  └──────────────────┘    └──────────────────────┘      │          │
│ │                                                        │          │
│ │  Installed: .27 (uv tool install) + .51 (nix-shell)   │          │
│ └────────────────────────────────────────────────────────┘          │
│                                                                      │
│ ┌─────────────────── OBSERVABILITY LAYER ──────────────────┐        │
│ │                                                          │        │
│ │  ┌──────────┐    ┌──────────┐    ┌──────────────┐       │        │
│ │  │ pi       │    │ OmniRoute│    │   Langfuse  │       │        │
│ │  │dashboard │    │ traces──▶│    │   (.13:3001)│       │        │
│ │  │ .ts      │    │          │    │              │       │        │
│ │  │ state    │    │          │    │  Dashboard   │       │        │
│ │  │ files    │    │          │    │  Evals       │       │        │
│ │  └──────────┘    └──────────┘    │  Cost per    │       │        │
│ │                                  │  session     │       │        │
│ │                                  └──────────────┘       │        │
│ └──────────────────────────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────────────┘
```

---

## Layer-by-Layer

### Session Memory Layer — What the agent remembers during a conversation

| Tool | What it does | Where | Status |
|------|-------------|-------|--------|
| **pi-memctx** | Memory packs — saves/retrieves observations, decisions, runbooks via keyword/semantic search. Injected at session start. | pi extension (`npm:pi-memctx`) | ✅ Active |
| **Headroom** | Compresses context >20K chars by 60-95%. Triggered by `headroom-bridge` extension for analysis/code/devops tags. | Docker on .13:8787 | ✅ Active |
| **Dashboard** | Writes JSON state files per session. Tracks agent activity, tool calls, tasks. Cross-machine SSH visibility via `pi-dashboard` Go TUI. | pi extension (`dashboard.ts`) | ✅ Active |

### Long-Term Memory Layer — What persists across sessions

| Tool | What it does | Where | Status |
|------|-------------|-------|--------|
| **Engram** | Session journal — captures raw conversations, extracts observations. Persistent log of what agents discussed. | Systemd service on .13:7437 | ✅ Active |
| **gentle-engram** | Pi bridge to engram. Reads `ENGRAM_URL=http://127.0.0.1:7437` via SSH tunnel from .27. Replaces memory-vault. Session capture, compaction recovery, private block redaction. | pi extension (`~/.agents`) | ✅ Active (tunnel must be re-established after reboot) |
| **Memctx packs** | Markdown knowledge files stored in Obsidian vault synced to memory packs. pi-memctx searches them at session start. | Obsidian → memctx | ✅ Active |
| **TencentDB Agent Memory** | 4-tier auto-memory: L0 raw → L1 facts → L2 scenarios → L3 persona. Auto-extracts preferences, conventions from conversations. | GitHub, v2 beta | ⏳ Wait for v2 stable |

### Code Intelligence Layer — What the agent knows about your code

| Tool | What it does | Scope | Installed |
|------|-------------|-------|-----------|
| **codebase-memory-mcp** | Machine-wide code intelligence. Tree-sitter AST indexing. Tracks agent learnings across ALL projects. Deterministic, no LLM. | Global | .27, .51 |
| **code-review-graph** | Per-project structural code graphs. Functions, classes, imports, calls, inheritance. SQLite `.db` per repo. Blast-radius analysis, semantic search, architecture overview. | Per-repo | .27, .51 |

**Key difference:** codebase-memory = "what agents learned about this codebase" (observations). code-review-graph = "what the code structure IS" (deterministic AST). They solve different layers.

### Observability Layer — What happened and what did it cost

| Tool | What it does | Where | Status |
|------|-------------|-------|--------|
| **Langfuse** | LLM observability platform. Traces every request, evaluates responses, tracks cost per session/model. Free tier. | Docker on .13:3001 | ✅ Active |
| **OmniRoute → Langfuse** | OmniRoute sends traces/metrics to Langfuse. Python sidecar on .13 syncs traces → SQLite for Go dashboard queries. | Planned | 🔜 Session Explorer Phase 1 |
| **Pi Dashboard** | Local state files tracking session activity and project tasks. | `.pi/dashboard/` per project | ✅ Active |

---

## Data Flow

```
User types in Pi
     │
     ├─▶ pi-memctx injects memory pack context at session start
     │
     ├─▶ headroom-bridge compresses if >20K chars
     │         └─▶ Headroom Docker (.13:8787) → 60-95% reduction
     │
     ├─▶ OmniRoute (.13:20129) routes to best LLM
     │         └─▶ Langfuse (.13:3001) records trace
     │
     ├─▶ codebase-memory-mcp / code-review-graph provide code context
     │
     └─▶ gentle-engram → engram (.13:7437) journals session
              │
              └─▶ tunnel: ssh -fNL 7437:127.0.0.1:7437 192.168.20.13
```

---

## SSH Tunnels Required

| Tunnel | Command | Purpose |
|--------|---------|---------|
| engram | `ssh -fNL 7437:127.0.0.1:7437 192.168.20.13` | gentle-engram → engram |