feat: observational memory — programmatic extraction + observation block

[platypusrex]

Summary

Adds observational memory (Phase 0) — programmatic extraction of structured observations from tool calls, stored in SQLite, injected into the system prompt. Observations survive compaction because they live in a separate table, not in message history.

Closes #65. Follow-up LLM-based extraction tracked in #69.

What it does

After every tool call, pure-function extractors produce typed observations from the tool name, args, and result. These are stored in SQLite and formatted into an <observations> block injected into the system prompt before each LLM call.

Extracted observations:

Tool	Type	Importance
edit_file	file_modified	7
write_file	file_created	7
read_file	file_read	3
run_command (success)	command_run	4
run_command (failure)	command_error	8
glob / grep	search_performed	3
todo_write	todo_updated	5
task	task_delegated	5

Observation block in system prompt:

<observations>
## Modified Files
- src/agent/index.ts (modified x 3)

## Errors
- Failed: bun test -> exit 1: TypeError...

## Commands
- bun check:types -> exit 0

## Searches
- grep "onToolResult" -> 3 matches
</observations>

Key design decisions:

• SystemPromptContext.observationBlock field (not string concatenation) — prompt content belongs in the prompt layer
• source: "programmatic" | "llm" on the Observation type — future-proofs for LLM extraction (feat: Observational Memory v2 — Observer/Reflector context management #69)
• 2000 token budget (not 800) — target models have 200K-1M+ context windows
• try/catch around observation storage — never crashes the agent loop
• Args captured at onToolCall time via Map, not looked up from store at result time

Files changed

New (6):

• src/memory/types.ts — Observation type definitions
• src/memory/store.ts — SQLite persistence layer
• src/memory/extractors.ts — Programmatic extractors for 8 tool types
• src/memory/working-memory.ts — Observation block builder with dedup + token budget
• tests/test-memory.ts — 37 unit tests
• tests/test-memory-integration.ts — 7 integration tests (full pipeline)

Modified (7):

• src/session/migrations.ts — Migration v5: observations table
• src/session/db.ts — setDatabaseForTesting for test injection
• src/agent/prompts/shared.ts — observationBlock on SystemPromptContext
• src/agent/prompts/build.ts + plan.ts — Include observation block
• src/agent/index.ts — observationBlock on RunAgentArgs, debug logging
• src/tui/hooks/use-agent-submit.ts — Extract observations + build block

Testing

• 44 tests, 130 assertions — all passing
• Unit tests: extractors (13), store (10), block builder (10), edge cases (4)
• Integration tests: full pipeline extraction-to-prompt (7) covering block placement, dedup, session isolation, read omission, denied/blocked handling, both build + plan modes
• Manual test: confirmed observations stored in SQLite and system prompt grew by expected amount on second turn

Out of scope

• LLM-based extraction (tracked in feat: Observational Memory v2 — Observer/Reflector context management #69)
• Staleness detection / cross-session persistence
• FTS5 / semantic retrieval

[changeset-bot]

🦋 Changeset detected

Latest commit: 0a0e8a5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
olliecode	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR