11 KiB
11 KiB
created, modified, type, tags, aliases
| created | modified | type | tags | aliases | |||
|---|---|---|---|---|---|---|---|
| 2026-08-03 15:42 | 2026-08-03 15:45 | note |
|
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 |