Obelisk Deep Dive: A Coding Agent's Retrieval Layer Should Be an Execution Database, Not a Wiki

> Source: Tommy (tommy0103) — https://tommy0103.github.io/project_silica/ > Project: Obelisk — turning coding-agent memory from passive recall of semantically similar fragments into findable, auditable, reproducible execution memory.

One-sentence summary

Obelisk's core insight: a coding agent's session is not a chat log but execution memory — it inherently has strong structure, a clear trunk, and verifiable outputs. The built-in retrieval layer should therefore be a queryable execution database, not semantic fragments flattened into a wiki.

Key points

• Context loss in recursive agent structures: Anthropic's dynamic workflows (May 2025) orchestrate multiple subagents via scripts, but intermediate results are invisible to the main agent — it only sees the workflow() tool call's return value. Agent interaction has evolved from conversation flows to trees to DAGs, making on-demand retrieval of intermediate context critical.
• Anti-wiki philosophy: Raw sessions are already structured data. Compiling them early into wiki/markdown pages flattens relationships among tool calls, files, subagents, workflows, and parent chains. The storage layer should preserve relationships and queryability.
• Boring tech, redefined problem: SQLite (storage) + FTS5 (full-text search, not vectors) + a JS query runtime (V8 sandbox) + JSONL as the raw evidence fallback layer.
• Tool results are an evidence fallback layer, not the retrieval trunk: what matters is the agent's own narration of tool results. Raw results are unfolded only for auditing or when the agent's reading is in doubt.
• Why not vector retrieval: RAG was path-dependent — people assumed AI can't search for itself and that memory should be passively recalled (an anthropomorphic myth). "The agent should know better than a RAG system what it wants to find." Coding sessions need precise queries like "which session touched this file" or "which session hit this error," not similarity matching.
• Social episodic memory vs execution memory: IM sessions are divergent, sparse, unverifiable; coding sessions are task-driven with a clear trunk and verifiable outputs (diffs, test results, file paths). Benchmarks like LoCoMo measure social episodic memory and shouldn't be conflated with execution memory performance.
• CodeAct as the retrieval language: agents write JavaScript against helper functions instead of a custom DSL — better composition, fewer round trips, native to LLMs, and safe in a V8 sandbox where the SQLite file is only a view over the raw trace.
• Progressive disclosure: SKILL.md exposes only search()/context()/sql() entry points plus high-frequency schema contracts; references files carry complex query patterns and retrieval semantics. SkillOpt evaluation exposed over-fetching (e.g., workflowTree exceeding token limits), fixed with lightweight summaries and drill-down by agent id.

Architecture highlights

The SQLite schema centers on execution structure: sessions, messages (with parent chains, token counts, skills), tool_calls, tool_results, workflows, subagents, workflow_agents, summaries, memories (soft-delete via archive-plus-write), index_state, and FTS5 virtual tables for messages and memories.

Memory layer

• Retrieval (--query) is strictly read-only; writing memories requires --attune mode with user confirmation, exposing remember() / forget().
• Durable conclusions must be explicitly approved, written as markdown, and registered — more conservative than auto-summarization.

Multi-source indexing (Claude + Codex)

• Unified schema with a source field rather than per-provider databases; Codex IDs get a codex: prefix; Codex root threads map to sessions, child threads to subagents; a lossy common model avoids provider-specific side tables.
• Project attribution for Codex is inferred from runtime signals (session_meta.payload.cwd, turn_context.payload.cwd, git branch/repository).
• DB path moved from ~/.claude/obelisk.sqlite to ~/.obelisk/obelisk.sqlite to avoid binding to any single provider.

Electron app

A companion app serves human browsing (session browser, recap cards, diffs, terminal output) over the same SQLite index, while the skill remains zero-dependency and optional-app-free.

Evaluation and limitations

• SkillOpt evaluations showed some "improvements" (v6/v7/v9) were likely rollout noise; real findings were over-fetch issues and new scenarios (compact workflow trees, forced search on empty results). The philosophy: optimize the path length for agents to get usable evidence, not raw SQLite speed.
• Limitations: only Claude Code / Codex formats supported; local SQLite may not scale to very large histories; the memory layer is currently very conservative (a single memory); naive read-only SQL checks can false-positive on string literals containing keywords like REPLACE.

Closing insight

> Agent transcripts are not chat logs; they are self-narrating execution traces.

Obelisk uses no novel technology — the contribution is reframing the problem: execution memory demands precise, structured, actively queried retrieval rather than passively recalled semantic fragments.

References

• Tommy, "Obelisk: Coding Agent 内置检索层应该是执行数据库，而不是 Wiki": https://tommy0103.github.io/project_silica/
• Anthropic Dynamic Workflows (2025-05-29): https://www.anthropic.com/news/dynamic-workflows