147 lines
11 KiB
Markdown
147 lines
11 KiB
Markdown
---
|
|
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 |
|