Obelisk

obelisk

Search and query local Claude Code, Codex, Kimi Code, Kiro, and Pi session history. Obelisk indexes sessions, messages, tool calls, tool results, summaries, subagents, workflows, workflow agents, parent chains, and raw JSONL lines into SQLite + FTS5.

Obelisk has several transcript sources. Treat all of them as ordinary sessions by default: Claude rows use source='claude', Codex rows use source='codex', Kimi Code rows use source='kimi', Kiro rows use source='kiro', and Pi rows use source='pi'. Use source only when provenance matters or the user asks to scope to one provider. Provider-specific records are projected into the same canonical tables; some providers may not emit every kind of subagent or workflow metadata.

Obelisk is a CodeAct memory layer: write a small JS query, run it locally, read the JSON, then answer. Do not turn history into a flat document or browse entire sessions by default.

Fresh Index and Sandbox Permissions

Treat a successful Obelisk invocation as a precondition for using its results. Obelisk refreshes ~/.obelisk/obelisk.sqlite before retrieval so the answer includes the latest sessions and can identify the invoking session. Never degrade to a stale, read-only index when that refresh cannot write.

In Codex workspace-write or managed sandboxes, ~/.obelisk may be outside the writable roots. If an Obelisk command fails with SQLITE_READONLY, EACCES, EPERM, attempt to write a readonly database, or another permission error for ~/.obelisk, rerun the same command with sandbox_permissions: "require_escalated". On another agent host, use its equivalent mechanism to grant write access to ~/.obelisk. Do not replace the failed command with direct SQLite, JSONL, or stale-index reads.

If write access is unavailable or the user denies escalation, stop and report the permission blocker. Retrieval is complete only when the Obelisk command exits successfully and returns its query result.

Quick Start

Fast keyword search (pass a unique nonce so Obelisk can recognize your own session in results):

obelisk --search "keyword" --nonce "$(uuidgen 2>/dev/null || echo "$$.$RANDOM.$RANDOM")"

Custom query:

1. Write a bounded JS query to a unique temp file — the as-typed file path is your invocation nonce:

   qdir=$(mktemp -d /tmp/obq.XXXXXX 2>/dev/null || { d="/tmp/obq.$$.$RANDOM"; mkdir "$d"; echo "$d"; })
   qfile="$qdir/query.mjs"

   The .mjs name lives inside the unique directory, so the mktemp template always ends on the X run (BSD mktemp requires that).

2. Run:

   obelisk --query "$qfile"

3. Parse JSON stdout and answer with concise evidence.

The query file runs inside (async () => { ... })(). Use return to emit JSON. Query scripts are read-only: remember() and forget() are not available, and sql() only accepts read-only SELECT/WITH queries.

Your Own Session In Results

Obelisk refreshes the index before each query, so your own live session shows up in results. The invocation nonce (--search --nonce, or the unique --query file path) lets Obelisk mark it: session projections in search() hits and sessions() rows carry is_invoking: true, and overview().current.session_id holds the invoking session id when known. Treat a session flagged is_invoking as your own current context, NOT as independent historical evidence. Resolution is newest-wins over recent matches; only a near-simultaneous same-nonce collision (or no match at all) leaves nothing marked and current.session_id null — identity is honestly unknown.

Context-Window Handoffs

When the current context begins with an Obelisk rollover handoff, read that handoff before searching. Treat its session_id as the default scope for recovering this task: pass it as sessionId to search() or other helpers. When you need evidence around the end of the previous context, call context() with the supplied message_uuid. Expand to global or cross-session search only when the task actually needs evidence outside that session.

Default First Pass

Start with helpers, not raw SQL. For the first Obelisk query in a task, normally call overview({ limit: 6 }) unless the user already gave an exact session_id, message uuid, or absolute file path.

For semantic or synthesis tasks, combine orientation, memory recall, and raw session evidence before deciding whether a detail pass is needed:

const map = overview({ limit: 6 });
const project = map.current.project?.project;
const topic = 'English topic terms translated from the user request';

return {
  orientation: map.current_project,
  prior_memories: memories({ project, query: topic, limit: 5 }),
  session_evidence: search(topic.replace(/[-_]/g, ' '), { project, limit: 8 }),
};

Use sql() only as an escalation path for exact joins, aggregations, or schema questions that helpers cannot express cleanly. Do not use raw SQL as a generic fallback for broad retrieval.

Intent Routing

Obelisk supports a small intent prefix layer after /obelisk. This is for output intent, not retrieval architecture.

Routing rules:

1. If the first word is recap, read references/recap/overview.md before the first query. Everything after recap is the recap target. Common app-generated prompts include /obelisk recap this week, /obelisk recap last week, /obelisk recap this month, and /obelisk recap last month; interpret these as natural period targets relative to the current date and timezone.
2. recap does not create a separate retrieval layer. It still uses overview(), memories(), helpers, and sql() only when needed.
3. Follow the overview's card-by-card sequence. Each card has its own retrieval pattern and writing file; retrieve that card's evidence, read that card's writing file, update the JSON, then move to the next card. Do not preload all recap references before the current card is written.
4. If the first word is not recap, do not load references/recap/overview.md. Continue with Query Routing below. Do not infer recap from broad requests for weekly/monthly summaries, charts, rankings, shareable cards, or playlist-style metaphors.

Reference Map

Use references by job, not by habit:

Query Routing

Before writing a query, classify the task. Progressive disclosure is useful, but skipping the relevant reference usually costs extra query rounds.

• Read references/query-patterns.md before the first query for broad synthesis, progress summaries, design history, ordinary weekly/monthly reviews, or questions that ask what the user did, learned, decided, tried, or abandoned. Start from the first-pass or one-shot synthesis pattern, then run a faceted detail pass if needed.
• Read references/retrieval-semantics.md before multi-step retrieval, scoped project/file/session searches, or synthesis/conclusion/history questions. It defines the query design frame.
• Read references/schema.md before raw sql() unless the needed table/column relationship is already explicit here. It is intentionally short and SQL-focused. Do this before running the SQL, not after a missing-column error. Do not start with raw SQL for broad synthesis unless helpers cannot express the needed aggregation or join.
• Read references/api-reference.md when helper option names, return fields, scalar shorthand behavior, or remember()/forget() details are unclear.
• Read references/pitfalls.md after an error or when FTS syntax, aliases, ordering, row shapes, or compact/raw tradeoffs are unclear.

If a helper row shape is unclear, first run a tiny scoped query and return Object.keys(row) or a compact sample. Do not invent field names.

For approved memory mutations, follow the Memory Layer section below first. Use references/query-patterns.md for copyable --attune scripts (Attune Approved Memory, Forget Approved Memory, Update Approved Memory), and references/api-reference.md only for exact parameter semantics.

Core API

search(text, opts?)

Full-text search across main messages, subagent messages, and workflow-agent messages.

Returns:

[{ message: { uuid, text, content_type, is_meta, role, timestamp, model, cwd, visibility, source },
   session: { id, title, project, started_at, source, is_invoking? },
   rank,
   context }]

session.is_invoking is true only when the hit belongs to the session that ran this query (see "Your Own Session In Results"); it is omitted otherwise.

context here means temporal neighbors: nearby messages in the same session by timestamp. It is not the parent chain. Use context(uuid) or trace(uuid) for causal/parent-chain context.

Use message.content_type to keep evidence boundaries intact: text is user/assistant visible language, thinking is trace/debug material, tool_use marks a tool-call message whose details live in tool_calls, and tool_result marks a tool-result message whose details live in tool_results. unknown is a conservative fallback. Do not treat thinking as a user-visible assistant conclusion. Real user input is type='user' plus content_type='text'; do not invent a separate user_message content type.

Use message.is_meta to separate transcript control-plane material from conversation evidence. is_meta=1 marks injected caveats, command envelopes, or other messages that entered the transcript as user-role content but should not be treated as the user's request by default. search() and thread() omit meta messages unless includeMeta: true is passed; context() and trace() preserve the current causal chain and expose is_meta on returned rows.

Pi can preserve a branch that was tried and later superseded as visibility='inactive'. Only Pi populates it: other sources either do not record supersession in their transcripts or discard it while indexing, so an empty inactive result never means nothing was abandoned -- only that this source cannot say. Default helpers return only visible evidence. Pass includeInactive: true to search(), context(), trace(), thread(), summaries(), raw(), fileHistory(), or failures() only when the abandoned path matters. Every returned message or evidence row is labeled with visibility; describe inactive evidence as something tried and then superseded, never as the final decision. hidden is reserved for display-suppressed or transport-only records and is never returned by these helpers, even with the option enabled.

Opts: { limit, sessionId, project, after, before, cwd, source, includeMeta, includeInactive }.

project is a SQL LIKE filter over sessions.project, not an exact project identity. Results are already ordered by FTS5 rank; lower rank sorts earlier. Prefer returned order over manually interpreting numeric rank unless you are deliberately using FTS5 semantics.

source can be 'claude', 'codex', 'deepseek', 'kimi', 'pi', or omitted. Omitted means search all indexed sources.

context(uuid, opts?)

Returns the full story around one indexed message:

{ message, parentChain, session, subagent, workflow }

Use this after search() finds a promising message. It is the usual way to expand vertically from one evidence point without dumping the whole session. The target and returned ancestors must be visible by default. Pass { includeInactive: true } to follow an explicitly superseded Pi path.

sql(query, ...params)

Read-only SQL SELECT/WITH with ? placeholders. Returns array rows. SQL is an escape hatch for exact structured joins and aggregations after the helper-first surface is insufficient; it is not the default retrieval entry point.

Before writing non-trivial SQL, read references/schema.md. It is the raw SQL field/join quick reference. The executable DDL is CLI-owned and is deliberately not duplicated in this docs-only skill. Common safe joins:

• tool_calls does not have timestamps. Join messages m ON m.uuid = tc.message_uuid.
• tool_results does not have timestamps. Join messages m ON m.uuid = tr.message_uuid.
• For project/session filters, join sessions s ON s.id = <table>.session_id.
• Prefer SQL-side GROUP BY, COUNT, MAX, ORDER BY, and LIMIT over hand-counting in the final answer.

Tables: sessions, messages, tool_calls, tool_results, summaries, memories, subagents, workflows, workflow_agents, messages_fts.