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

Forum topic · 小凯 · 2026-06-19

Summary

Obelisk is a retrieval layer for coding agents built by Tommy (tommy0103) that treats agent session history as an execution database rather than semantically compressed wiki pages. Its core insight: coding agent sessions are execution memory with strong structure (messages, tool calls, files, subagents, workflows) and verifiable outputs, so they should be stored in SQLite with FTS5 full-text search instead of vector embeddings. The agent queries the database by writing JavaScript scripts that run in a V8 sandbox, giving composability and efficiency that custom DSLs and repeated tool calls lack. Tool results are deliberately kept as an evidence backstop outside the retrieval backbone, since the agent's narration of results carries the semantic state. A conservative memory layer archives durable conclusions only after explicit user approval via a write-gated mode. Obelisk supports multi-source indexing (Claude Code and Codex) under a unified schema, ships as both a zero-dependency skill and an optional Electron browsing app, and was iterated through a SkillOpt evaluation framework that exposed over-fetching issues. The project argues that RAG-style vector retrieval is path-dependent overreach for agent memory: precise lookup by file, error, or tool outperforms fuzzy similarity for execution traces.

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

Key points

Core insight: Coding agent sessions are not chat logs but *execution memory* — strongly structured, with a clear backbone and verifiable outputs. The built-in retrieval layer should therefore be a queryable execution database (SQLite + FTS5), not semantic fragments flattened into a wiki.

The problem: 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 — only the workflow() tool return is exposed, to avoid blowing up the context window.
Agent interaction paradigms have evolved from conversation flows to trees to DAGs, making on-demand retrieval of intermediate context critical.
The author's first idea — URI addressing (agent://<session-id>/<message-id>/...) with CLI queries — failed on two counts: too many tool calls for frequent retrieval, and low adherence to a custom DSL.

Architecture: SQLite + FTS5 + JS query runtime

SQLite for structured session storage, FTS5 full-text search (not vector search), a JS query runtime in a V8 sandbox, and raw JSONL session data as an evidence backstop layer.
Deliberately anti-wiki: prematurely compiling sessions into markdown flattens relations among messages, tool calls, tool results, files, subagents, workflows, and parent chains. The storage layer must preserve relations and queryability.
Schema tables: sessions, messages, tool_calls, tool_results, workflows, subagents, workflow_agents, summaries, memories, index_state, plus FTS5 virtual tables (messages_fts, memories_fts).
Tool results are kept out of the retrieval backbone — the agent's narration of tool results is the backbone; raw results are evidence for audit only.

Why vector retrieval is not the answer

RAG's dominance is attributed to path dependence: distrust of AI's ability to search for itself, and an anthropomorphic myth that memory should be passively recalled.
Execution memory vs. social episodic memory: IM sessions are divergent, unverifiable, and suited to "similar fragments"; coding sessions are task-driven, verifiable (diffs, tests, file paths), and need precise lookup — "which session touched this file?", "which run hit this error?".
Benchmarks like LoCoMo (IM-style sessions) should not be used to evaluate coding-agent memory modules.

CodeAct as the retrieval language

The agent writes JavaScript query scripts instead of using a custom DSL: better composability, one script can aggregate large amounts of information, JS is native to LLMs, and the V8 sandbox plus SQLite-as-view-of-JSONL provides safety.
Progressive disclosure: SKILL.md exposes only search()/context()/sql() entry points with high-frequency schema contracts; references/ documents cover query patterns, retrieval semantics (Scope First, Plan Before Probe, Structure Before Text, Evidence Before Conclusion), and full schema. Too-thin prompts leave references unread; too-thick ones eat attention.
Overfetch control: designed helper functions with lightweight defaults (e.g., compact workflow trees with drill-down by agent_id) saved significant tokens versus raw SQL dumping full messages.

Key design judgments

Backbone retrieval + on-demand expansion: sessions are searched along the main conversation backbone; subagents, workflows, tool results, and raw JSONL are folded evidence layers expanded via a raw() window when needed.
Anti-handoff scope creep: Obelisk's main value is retrieval, evidence synthesis, and memory — not a handoff-specific tool.
Memory layer: retrieval finds evidence, but durable conclusions must be explicitly approved, written as markdown, and registered for recall. Read-only --query mode vs. --attune mode that exposes remember()/forget() mutations; updates are archive-plus-write (soft delete + new version) with path resolution tied to the source session's project path.

Multi-source indexing and Electron app

Unified schema with a source field indexes both Claude Code and Codex sessions: Codex IDs get a codex: prefix, root threads map to sessions, child threads to subagents, and a lossy common model skips Codex-specific runtime crumbs. Project attribution is inferred from cwd and git signals.
DB path moved to ~/.obelisk/obelisk.sqlite to avoid binding to any provider directory.
An optional Electron app shares the same SQLite index for human browsing (session browser, recap cards), with substantial UI complexity (e.g., SessionDetail.vue edited 89 times).

Evaluation via SkillOpt

Multi-round SkillOpt runs revealed that apparent gains in v6/v7/v9 may be rollout noise; real issues found were over-fetching in workflowTree/context/fileHistory, plus new scenarios (compact workflow trees, empty results must trigger search).
Philosophy: optimize the path length for the agent to obtain usable evidence, not the raw speed of SQLite queries.

Distribution

Skill side: zero dependencies, copy-to-use, no npm install required. App side: optional Electron companion sharing the DB.
Packaging pain points: better-sqlite3 native module needs per-platform builds; sandbox issues with DNS, spawn EAGAIN, runtime downloads; zip artifacts work in sandbox while DMG creation via hdiutil requires elevated permissions.

Why it works — and limitations

1. Coding agent sessions genuinely resemble execution memory (clear backbone, project boundaries, tool calls, file paths). 2. Vector retrieval is over-generalized; execution memory needs precise lookup. 3. The anthropomorphic memory myth misleads design — agent history is more like a work log requiring active queries.

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

Limitations: supports only Claude Code / Codex session formats; local SQLite may not scale to massive histories; the memory layer is very conservative (only one global memory in practice); naive read-only SQL protection can false-positive on string literals containing REPLACE.

References

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