tommy0103/obelisk/skill-doc

obelisk

Retrieve local coding-agent history through the installed obelisk CLI. Write a bounded JS query, read its JSON result, then answer from evidence.

Retrieval workflow

1. Choose the narrowest project, file, session, time range, or topic scope.

Read the matching reference below before writing the query.

1. Normally start a new task with overview({ limit: 6 }); skip orientation

for an exact session ID, message UUID, or absolute file path. Overview is a navigation map, not evidence.

1. Recall prior conclusions with memories() and verify against session

evidence with search() or scoped helpers. Use English memory query terms. Expand selected hits with messages() rather than loading entire sessions.

1. Group, deduplicate, and project inside the query. Return stable IDs and short

snippets; keep synthesis JSON around 10k–12k characters when possible.

1. Answer with concise evidence. Identify prior memories naturally when they

influence the answer. Offer to save a durable, new conclusion; wait for approval before writing the memory file or changing memory records.

Treat is_invoking: true as your current session, not independent historical evidence. Ordinary conversation evidence uses visible, non-meta text; thinking and tool output have different evidentiary roles. Read retrieval semantics before querying those surfaces or superseded branches.

Run a query

Use a unique temporary directory so the query path cannot collide:

qdir=$(mktemp -d /tmp/obq.XXXXXX 2>/dev/null || { d="/tmp/obq.$$.$RANDOM"; mkdir "$d"; echo "$d"; })
qfile="$qdir/query.mjs"
cat > "$qfile" <<'JS'
const hits = search('auth fix', { limit: 5 });
return hits.map(h => ({
  session_id: h.session.id, uuid: h.message.uuid,
  content_type: h.message.content_type,
  snippet: h.message.text?.slice(0, 240),
}));
JS
obelisk --query "$qfile"

The CLI runs the file in an async wrapper; return emits JSON. The helper API is read-only, but --query evaluates JavaScript with the privileges of the CLI process — it is not an isolated sandbox. Only run trusted scripts. For broad history, adapt the first-pass recipe in query patterns instead of this tiny keyword example.

For a quick keyword lookup:

obelisk --search "keyword" --nonce "obq-<unique-token-you-invent>"

Type a unique literal nonce: shell substitutions cannot identify the invocation in the transcript. Query-file identity resolves through its recorded path or script content.

Fresh index and permissions

A successful CLI invocation is required: it refreshes ~/.obelisk/obelisk.sqlite before retrieval. Never degrade to a stale, read-only index when refresh fails.

If the command fails with a write-permission error for ~/.obelisk (such as SQLITE_READONLY, EACCES, or EPERM), rerun the same command with sandbox_permissions: "require_escalated", or the host's equivalent write permission mechanism. If access is unavailable or denied, stop and report the blocker. Direct SQLite or JSONL reads do not substitute for a successful refresh.

Choose helpers

The default retrieval surface is:

Specialized and legacy helpers remain callable; read their API contracts when needed. Check uncertain option names and row fields before relying on them.

Load references by task

Load only the references needed for the current task. Each reference owns its contracts or recipes; do not preload the whole directory.

Route to recap only when the first word after /obelisk is recap; ordinary weekly/monthly summaries do not select that workflow.

Approved memory changes run locally through a separate mutation entry point: obelisk --attune /tmp/register-memory.mjs. Retrieve the necessary IDs first with --query; --attune exposes only remember() and forget().