diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index 58387aa..42c9265 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -13,12 +13,12 @@ "state": { "type": "markdown", "state": { - "file": "300 areas/350 AI/Ai memory management.md", - "mode": "source", + "file": "300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md", + "mode": "preview", "source": true }, "icon": "lucide-file", - "title": "Ai memory management" + "title": "Home Network Map Overview" } } ] @@ -181,10 +181,10 @@ "state": { "type": "file-properties", "state": { - "file": "300 areas/350 AI/Ai memory management.md" + "file": "300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md" }, "icon": "lucide-info", - "title": "File properties for Ai memory management" + "title": "File properties for Home Network Map Overview" } } ], @@ -207,11 +207,11 @@ "templater-obsidian:Templater": false } }, - "active": "7066c9273c6fb936", + "active": "29ff3dd1c6bfd474", "lastOpenFiles": [ - "300 areas/350 AI/Ai planning flow control tools.md", "300 areas/350 AI/Ai memory management.md", "300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md", + "300 areas/350 AI/Ai planning flow control tools.md", "300 areas/360 Dev-Ops Network Computers/Local Wep Apps.md", "300 areas/350 AI/AI Tools to try.md", "300 areas/360 Dev-Ops Network Computers/Pi Neovim Coding Harness.md", diff --git a/300 areas/350 AI/Ai memory management.md b/300 areas/350 AI/Ai memory management.md index 17130c8..b6df7cc 100644 --- a/300 areas/350 AI/Ai memory management.md +++ b/300 areas/350 AI/Ai memory management.md @@ -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 | diff --git a/300 areas/350 AI/Ai planning flow control tools.md b/300 areas/350 AI/Ai planning flow control tools.md index d59e56c..51e7074 100644 --- a/300 areas/350 AI/Ai planning flow control tools.md +++ b/300 areas/350 AI/Ai planning flow control tools.md @@ -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) |