obelisk

Savant verdict: Review advised

Security analysis or source-hub review identified patterns requiring attention.

Live evaluation

Not evaluated yet. Workspaces can request a live evaluation.

Security assessment

Scan pending.

Structure

• No license declaredConfirm you may reuse this skill before importing it into your repository.
• The source hub's security checks flagged this skillGen Agent Trust Hub: warn (The obelisk skill enables querying local session history from various agents via a CLI. It uses a workflow that generates and executes JavaScript queries at runtime and encourages the agent to request escalated permissions if database access is restricted. It also processes untrusted historical data, making it susceptible to indirect prompt injection.); Snyk: warn (Risk: MEDIUM · 1 issue)

SKILL.md

---
name: obelisk
description: >
  Search and query past Claude Code, Codex, Kimi Code, Kiro, OMP, 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

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.
2. 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.
3. 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.
4. Group, deduplicate, and project inside the query. Return stable IDs and short
   snippets; keep synthesis JSON around 10k–12k characters when possible.
5. 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:

```bash
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. Queries are
read-only, with no filesystem or network access inside the script. For broad
history, adapt the first-pass recipe in query patterns instead of this tiny
keyword example.

For a quick keyword lookup:

```bash
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:

| Helper | Purpose |
|---|---|
| `overview` | Orient to projects and recent entry points. |
| `sessions` | Locate sessions under structural filters. |
| `search` | Find message evidence by topic. |
| `messages` | Read one message, a bounded window, or a session interval (CLI 0.3.0+). |
| `memories` | Recall previously saved conclusions. |
| `summaries` | Read recorded session summaries. |
| `sql` | Express joins or aggregations the other helpers cannot. |

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.

| Before doing this | Read |
|---|---|
| Broad synthesis, design history, progress summaries, ordinary weekly/monthly reviews, or what the user did, learned, decided, tried, or abandoned | [Query patterns](references/query-patterns.md) and [retrieval semantics](references/retrieval-semantics.md). |
| Scoped project/file/session searches, multi-step retrieval, correlation, or evidence classification | [Retrieval semantics](references/retrieval-semantics.md). |
| Choosing helper options, fields, paging, or specialized/legacy helpers | [API reference](references/api-reference.md); for message expansion, the [messages contract](references/api-reference.md#messagesoptsoruuid). |
| Writing raw SQL | [Schema](references/schema.md) before execution. |
| Saving, archiving, or updating memory | [Memory workflow](references/memory-workflow.md) before writing files or running a mutation. |
| Workflow-specific retrieval | [Advanced helpers](references/advanced-helpers.md). |
| Recovering from an error or resolving FTS, ordering, row-shape, or raw-record surprises | [Pitfalls](references/pitfalls.md). |
| Explicit `/obelisk recap ...` | [Recap overview](references/recap/overview.md) before the first query, then follow its card-by-card disclosure. |

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()`.