sam/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sam-4screen-desktop 2026-8-3:15:59:15

Browse Source
This commit is contained in:
Sam Rolfe
2026-08-03 15:59:15 +10:00
parent f387cfed9d
commit 6a91de3ba3
3 changed files with 305 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
300 areas/350 AI/Ai memory management.md
View File

@@ -1,10 +1,146 @@
---
created: 2026-08-03 15:42
modified: 2026-08-03 15:42
modified: 2026-08-03 15:45
type: note
tags: []
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 |

162
300 areas/350 AI/Ai planning flow control tools.md
View File

@@ -1,10 +1,168 @@
---
created: 2026-08-03 15:43
modified: 2026-08-03 15:43
modified: 2026-08-03 15:45
type: note
tags: []
tags:
- ai
- planning
- flow-control
- architecture
aliases: []
---
# [[Ai planning flow control tools]]
## WhereWoof Implementation Pipeline
```
┌─────────────────────────────────────────────────────────────────────┐
│ WHERE WOOF IMPLEMENTATION PIPELINE │
│ │
│ ┌──────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ OpenSpec │────▶│ Plannotator │────▶│ Archon │ │
│ │ │ │ │ │ │ │
│ │ "What │ │ "Let me │ │ "I'll │ │
│ │ to │ │ think │ │ run the │ │
│ │ build" │ │ first" │ │ agents" │ │
│ └────┬─────┘ └──────┬──────┘ └─────┬──────┘ │
│ │ │ │ │
│ proposal.md PLAN.md Workspaces │
│ specs/*.md (exploratory) Worktrees │
│ design.md Browser review Concurrent sessions │
│ tasks.md Approve/deny State persistence │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Formal artifacts Interactive gating Execution harness │
└─────────────────────────────────────────────────────────────────────┘
```
---
## OpenSpec — Spec-Driven Planning
**What:** CLI + pi extension (`@fission-ai/openspec` v1.3.1) for generating structured artifacts per change.
**Pipeline:** `proposal → specs → design → tasks`
| Artifact | Purpose |
|----------|---------|
| `proposal.md` | WHY — problem statement, scope |
| `specs/*.md` | WHAT — ADDED/MODIFIED/REMOVED requirements with testable scenarios |
| `design.md` | HOW — architecture decisions, risks, migration plan |
| `tasks.md` | Implementation checklist (`- [ ]` format) |
**Pi skills (4):**
| Skill | Trigger | Purpose |
|-------|---------|---------|
| `openspec-propose` | `/opsx:propose "name"` | Create a new change with all artifacts |
| `openspec-apply-change` | `/opsx:apply` | Implement tasks one-by-one, checking boxes |
| `openspec-explore` | `/opsx:explore` | Thinking partner — explores codebase, draws diagrams, never writes code |
| `openspec-archive-change` | `/opsx:archive` | Archive completed change |
**Current state:** Initialized at `~/chats/sys_config/openspec/` but empty — no active changes.
---
## Plannotator — Interactive Plan Review
**What:** pi extension (`@plannotator/pi-extension` v0.19.10) with browser-based plan approval UI. Toggle with `/plannotator` or Ctrl+Alt+P.
**Two gated phases:**
```
PLANNING PHASE EXECUTING PHASE
┌───────────────────┐ ┌──────────────┐
│ Tools: grep, find,│ approve │ Full tool │
│ ls, submit_plan │─────────────────▶│ access │
│ Writes: .md only │ │ │
│ No: code edits, │ │ [DONE:n] │
│ installs, commits │ │ markers │
└───────────────────┘ └──────────────┘
```
**Browser review:** Agent writes `PLAN.md` → `plannotator_submit_plan` opens browser UI → you review and approve/annotate.
**Storage:** `~/.plannotator/plans/`, history at `~/.plannotator/history/{project}/{slug}/`.
**Current state:** No WhereWoof plan exists yet. No `.pi/plannotator.json` project config.
---
## Archon — Persistent Execution Harness
**What:** Web-based orchestration layer on top of Pi. `ghcr.io/coleam00/archon:latest` v0.3.10. Runs on .27:3090 (Docker).
**Features:**
- Workspaces and Git worktrees for project isolation
- Concurrent agent sessions with queuing (max 10)
- State persistence via SQLite (`/.archon/archon.db`) — resume sessions after closing
- Multi-platform: Web, Telegram, Slack, Discord
- Uses Pi as its coding agent (`DEFAULT_AI_ASSISTANT=pi`)
**Current state:** Running and healthy, but empty workspaces — not yet configured for WhereWoof.
---
## The Three-Stage WhereWoof Flow
### Stage 1: OpenSpec initializes the formal spec
```bash
/opsx:propose "where-woof-website"
```
Generates all 4 artifacts:
- `proposal.md` — two-system architecture justification
- `specs/frontend-pet-tracker/spec.md` — QR scan, location, pet info display
- `specs/admin-dashboard/spec.md` — user/payment/device management
- `design.md` — Go net/http + HTMX + Laravel Filament
- `tasks.md` — 8 implementation phases as checkboxes
### Stage 2: Plannotator gates execution
Activate `/plannotator`. Pi can only read and plan during this phase. When `PLAN.md` is ready, browser review lets you annotate specific sections before approving full tool access.
### Stage 3: Archon manages long-running execution
Open `http://192.168.20.27:3090`, create a workspace pointing at the WhereWoof repo, and Archon:
- Kicks off `/opsx:apply` for task-by-task implementation
- Persists conversation state — resume anytime
- Queues concurrent agent sessions for parallel work (frontend + admin)
- Tracks task completion
---
## Goose & CrewAI — Evaluated
### Goose (Block / Linux Foundation)
| Aspect | Detail |
|--------|--------|
| **What** | Terminal-first AI agent in Rust. MCP-native. Apache 2.0. |
| **Vs pi** | Same coding agent slot. No sub-agent system. No persistent memory (upstream). Value is MCP extensibility + recipe-based automation. |
| **Verdict** | ❌ **Redundant.** Pi already fills the terminal coding agent role with sub-agent orchestration. Goose's MCP ecosystem is broader but doesn't fill a gap. |
### CrewAI
| Aspect | Detail |
|--------|--------|
| **What** | Python framework for role-based multi-agent orchestration. Define agents with roles (Researcher, Writer, Reviewer) and they collaborate. |
| **Vs existing** | Orthogonal. It's for building standalone multi-agent Python applications, not enhancing the coding loop. Overlaps with LangGraph. |
| **Verdict** | ❌ **Not worth adding.** No gap in the pi coding workflow. Consider if building a separate multi-agent research/review pipeline later. |
### What to use instead
| Your need | Right tool |
|-----------|-----------|
| Spec-driven planning | OpenSpec |
| Interactive plan review + gated execution | Plannotator |
| Long-running session persistence | Archon |
| Multi-agent Python applications (future) | LangGraph (planned later) |
| Simple role-based agent pipelines (future) | CrewAI (if LangGraph is too heavy) |
---
## Current Gaps for WhereWoof
| Gap | Action |
|-----|--------|
| No OpenSpec change | Run `openspec new change "where-woof-website"` |
| No Plannotator plan | Activate `/plannotator`, write PLAN.md |
| Archon workspaces empty | Create workspace → `http://192.168.20.27:3090` |
| No task tracking | Use Pi Dashboard `register_task` tool (project-local .pi/dashboard/tasks/todo.txt) |