SPEC: Coding Agent Sidecar

Summary

A file-watcher-based sidecar that observes coding agent session transcripts and ingests them as structured Basic Memory notes. No hooks, no plugins, no coupling to agent internals. Just watches files and builds a knowledge graph.

Problem

Coding agents (Claude Code, Codex, Cursor, OpenCode) forget everything between sessions. Solutions like Letta's claude-subconscious inject themselves into the agent's runtime — fragile, vendor-specific, opaque. CLAUDE.md is a single flat file with no structure or search.

Users need persistent, searchable, cross-agent memory that:

• Survives across sessions
• Works across different coding agents
• Is human-readable and editable
• Builds structured knowledge, not just raw logs

Approach

Watch session files → Extract knowledge → Write BM notes → Available via MCP

The sidecar never touches the coding agent. It reads session transcript files from disk, runs an extraction agent over them, and writes structured Basic Memory notes. The coding agent picks up that knowledge on its next session via BM's MCP server (already installed).

┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
│ Claude Code  │     │   BM Sidecar     │     │ Basic Memory │
│ Codex / etc  │     │                  │     │              │
│              │     │  File Watcher    │     │  Knowledge   │
│  writes to:  │────▶│  ↓               │────▶│  Graph       │
│  ~/.claude/  │     │  Extract Agent   │     │              │
│  sessions/   │     │  ↓               │     │  MCP Server  │
│              │     │  Write BM Notes  │     │  ↑           │
│              │◀────────────────────────────────┘           │
│  (reads via  │     │                  │     │              │
│   MCP tools) │     │                  │     │              │
└──────────────┘     └──────────────────┘     └──────────────┘

Session File Locations

Extraction Model

The extraction agent processes each session transcript and produces:

1. Session Summary Note

memory/sessions/YYYY-MM-DD-short-description.md

---
title: "Refactored auth middleware"
type: session
agent: claude-code
project: /Users/paul/dev/basic-memory
duration: 45min
created: 2026-03-14
---

# Refactored auth middleware

## Observations
- [decision] Switched from JWT to session tokens for API auth
- [decision] Added rate limiting middleware at 100 req/min
- [pattern] Agent struggled with circular imports — resolved by extracting types to shared module
- [learning] pytest-asyncio requires `mode = "auto"` in pyproject.toml for fixture scoping
- [files_changed] src/auth/middleware.py, src/auth/tokens.py, tests/test_auth.py
- [error_resolved] Fixed "RuntimeError: Event loop is closed" by using asyncio.Runner

## Relations
- updates [[Auth Architecture]]
- relates_to [[API Rate Limiting]]
- follows [[Session 2026-03-13 - Initial Auth Setup]]

2. Entity Updates

If the session references or modifies known entities (people, projects, architectural decisions), update existing notes:

## Observations (appended)
- [update] Auth now uses session tokens instead of JWT (changed 2026-03-14)

3. Gotcha / Learning Notes

Reusable lessons extracted to their own notes:

---
title: "pytest-asyncio fixture scoping"
type: learning
---

# pytest-asyncio fixture scoping

## Observations
- [fact] pytest-asyncio requires `mode = "auto"` in pyproject.toml for proper fixture scoping
- [fact] Without this, async fixtures silently use function scope even when session scope is specified
- [source] Discovered during auth middleware refactor (2026-03-14)

Extraction Categories

The extraction agent looks for:

Implementation Options

Option A: bm watch-sessions

New CLI command that watches session directories and runs extraction.

bm watch-sessions --agent claude-code --project my-project

• Watches ~/.claude/sessions/ for new/modified files
• Runs extraction on completed sessions (detect session end by file age or explicit marker)
• Writes notes to configured BM project

Option B: OpenClaw plugin enhancement

Add session watching to openclaw-basic-memory plugin.

• Plugin already has file watching infrastructure (bm watch)
• Could watch session dirs alongside memory files
• Extraction runs as background task after session ends
• Natural fit since OpenClaw users already have BM + the plugin

Option C: Standalone sidecar process

Separate process/daemon, not tied to BM CLI or OpenClaw.

bm-sidecar --watch ~/.claude/sessions/ --project my-project

• Most portable — works without OpenClaw
• Could package as a standalone binary
• Systemd/launchd service for always-on watching

Recommendation: Start with Option A (bm watch-sessions) for dogfooding, then Option B for OpenClaw users. Option C later if there's demand from non-OpenClaw users.

Extraction Agent

The extraction step needs an LLM to produce structured notes from raw transcripts. Options:

• Cheap model (gpt-4.1-mini, Haiku) for routine extraction — most sessions are straightforward
• Configurable — let users pick their model
• Local option — Ollama for privacy-sensitive codebases
• Prompt template — tuned for each agent's transcript format

Key prompt behaviors:

• Focus on decisions and learnings, not play-by-play
• Deduplicate against existing BM notes (search before write)
• Link to existing entities via wiki-links
• Skip boilerplate (tool confirmations, file listings, etc.)
• Respect .gitignore patterns — don't extract secrets or sensitive paths

Deduplication

The extraction agent should search BM before writing:

1. Search for existing notes about the same topic
2. If found, append new observations rather than creating duplicates
3. If a learning/gotcha already exists, skip or update confidence

This prevents the knowledge graph from filling with redundant session notes.

Privacy / Security

• Session transcripts may contain secrets (API keys, passwords, private code)
• Extraction agent should strip sensitive content before writing notes
• Configurable: opt-in per project, exclude patterns, redact regex
• Local LLM option for air-gapped environments

Why This Beats Letta's Approach

Open Questions

1. Session end detection — How to know a session is "done"? File modification time threshold? Explicit end markers?
2. Incremental vs batch — Process sessions as they happen, or batch at end of day?
3. Cross-project memory — Should learnings from project A be visible in project B? (Probably yes for gotchas/learnings, no for project-specific context)
4. Cursor/Windsurf support — Session file formats vary. Start with Claude Code + Codex, expand later.
5. Token cost — Extraction uses LLM calls. Budget ~$0.01-0.05 per session with a cheap model. Worth tracking.

Prior Art

• Letta claude-subconscious — Hook-based, opaque, Claude Code only
• CLAUDE.md — Flat file, no structure, no search, single project
• Codex AGENTS.md — Same limitations as CLAUDE.md
• OpenClaw memory plugins — Vector-based, opaque (memory-lancedb-pro, memory-core)
• BM auto-capture — Already indexes OpenClaw conversations as daily notes. This extends the same pattern to coding agent sessions.