tommy0103andClaude Opus 4.8
60d47a852e
The desktop app now indexes through the shared provider adapters + persist
layer (scripts/providers/{claude,codex}, scripts/persist, scripts/parsing)
instead of maintaining its own parallel indexer. buildIndex shrinks from
~1173 to ~592 lines, eliminating the skill<->app parse duplication that
Phase 5 set out to remove. electron-vite bundles the .ts core from source
with better-sqlite3 injected; the provider->parsing graph stays
node:sqlite-free so nothing drags node:sqlite into the app.
Also fix a misleading log: when a manual rebuild tears down the worker
mid-build, the cancelled background build is a deliberate stop, not a
failure. Guard the service's failure log with the stopped flag so it no
longer prints "Obelisk index build failed: Indexer worker stopped" on
every rebuild.
- CONTEXT.md: provider-adapter + single-persist + node:sqlite-free parsing.
- docs/adr/0005: app builds with electron-vite (TS+ESM), packages with
electron-builder; preload CJS for sandbox; app consumes core from source.
Verified: full suite 121/121; a node:sqlite-adapter dogfood of the rebuild
path over real data (969 files, 285 sessions, FTS rebuilt) runs clean; app
Rebuild confirmed in real Electron/better-sqlite3.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
3.6 KiB
Obelisk
Obelisk is explicit memory infrastructure for coding agents: it indexes local Claude Code and Codex transcripts into a queryable SQLite evidence layer, and a CodeAct runtime lets an agent write a small query, run it, and answer from real session history. This glossary pins the terms that are specific to Obelisk; it is not a spec.
Runtime interface
Runtime interface:
The public contract, expressed as four verbs — build, search(text),
query(code), attune(code). Skill, CLI, and MCP are transports over this same
shape; none of them add their own retrieval surface.
Avoid: API, tool surface
CodeAct:
The interaction style where an agent writes JavaScript that runs inside the
query(code) sandbox and returns JSON, rather than calling many fine-grained
tools. This is Obelisk's core design choice.
Avoid: tool-calling, function-calling
Helper:
A convenience accessor available only inside the query(code) sandbox
(overview, search, context, sql, memories, …). Helpers are never
promoted to an external tool surface.
Indexing
Provider adapter:
A pure per-source module (claude, codex, later opencode, pi, …) that discovers a
source's transcript files and parses one into a stream of records. It never opens
or writes a database; adding a source means adding one adapter. The shared pure
parse/discover helpers live in scripts/parsing.mjs, which imports only
node:fs/path/os — deliberately node:sqlite-free so the compiled providers can be
consumed by the app (whose Electron runtime has no node:sqlite).
Avoid: parse core, parser, ingest
Record: One normalized row destined for the index (session, message, tool call, tool result, summary, subagent, workflow, …), emitted by a provider adapter before any persistence happens.
Persist layer:
The single shared, provider- and binding-agnostic writer that consumes records
from any adapter and writes them into an injected SQLite handle inside a
transaction. The binding is injected — node:sqlite (skill/CLI) or
better-sqlite3 (app) — so there is one persist implementation, not one per
binding.
Avoid: writer, sink, DAO
Daemon indexing mode: Continuous incremental indexing driven by a long-lived process (the desktop app, later a CLI daemon) that watches transcript directories and keeps the index fresh as files change. Avoid: watcher mode, live indexing
Passive pull mode: On-demand incremental indexing performed by the skill when there is no active daemon: an invocation of the runtime brings the index up to date, then answers. Avoid: lazy indexing, on-read indexing
index_state:
The bookkeeping table shared by both indexing modes. It records, per transcript
path, the last-seen mtime and lines_processed (enabling resume-from-line
incremental indexing), plus heartbeat/last-build markers used for daemon
arbitration.
Daemon arbitration:
The mechanism by which the passive pull mode detects a fresh daemon (via
__app_heartbeat__ and __app_last_successful_build__ markers in index_state)
and skips its own indexing. Because a fresh daemon owns writes, the two persist
layers never write concurrently.
Memory
Queryable session memory: The evidence layer — real sessions, messages, tool calls, subagents, workflows — that an agent queries on demand. Obelisk deliberately does this instead of implicit/ambient memory. Avoid: implicit memory, ambient memory, auto-recall
Approved durable memory:
Human-approved conclusions persisted as markdown plus a registry record, via
attune(code) calling remember()/forget(). Auditable and revocable.
Avoid: long-term memory, vector memory