obelisk/CONTEXT.md

# 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