Obelisk
Obelisk indexes past agent sessions (Claude Code, Codex, Kimi Code, Pi) into a queryable SQLite database with a CLI skill for agents and an Electron app for humans.
tommy0103 · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tommy0103/obelisk技能说明
name: obelisk description: > Search and query past Claude Code, Codex, Kimi Code, and Pi session history. Reactive: when the user asks "how did I fix X", "what did we do last time", "find the session where", "上次怎么修的", "之前的session", "历史记录". Proactive: when the user references past work you lack context for, when you're about to modify a file with complex edit history, when the user says "继续之前的" or "continue where we left off", or when understanding prior decisions would improve your current response. Memory: when the user says "记住这个", "remember this", "写入记忆", "save this conclusion", or when you determine a retrieval result contains a conclusion worth persisting. allowed-tools:
- Read
- Bash(obelisk:*)
- Write
obelisk
Search and query local Claude Code, Codex, Kimi Code, 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 four 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', 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:
-
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
.mjsname lives inside the unique directory, so themktemptemplate always ends on theXrun (BSDmktemprequires that). -
Run:
obelisk --query "$qfile" -
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.
| Intent | Description | Reference |
|---|---|---|
recap [target] | Generate weekly/monthly recap card content for app handoff or share-sty |