obelisk

obelisk

~/.claude/ と ~/.codex/ に保存されている Claude Code および Codex のセッション履歴を検索、クエリできます。 Obelisk はセッション、メッセージ、ツール呼び出し、ツールの結果、要約、サブエージェント、ワークフロー、ワークフローエージェント、親チェーン、未加工の JSONL 行を SQLite + FTS5 にインデックス化します。

Obelisk には 2 つのトランスクリプトソースがあります。デフォルトでは、どちらも通常のセッションとして扱います。 Claude の行は source='claude'、Codex の行は source='codex' で、ID には codex: が付与されます。出所が重要な場合、またはユーザーが特定のプロバイダーに対象を限定するよう求めた場合にのみ、source を使用してください。Codex のサブエージェントの子スレッドは同じ subagents テーブルにマッピングされます。Codex は Claude 形式のワークフローメタデータを出力しないため、Codex のワークフロー行が存在しない場合があります。

Obelisk は CodeAct メモリレイヤーです。短い JS クエリを書いてローカルで実行し、JSON を読み取ってから回答してください。デフォルトでは、履歴をフラットなドキュメントに変換したり、セッション全体を閲覧したりしないでください。

クイックスタート

スキルディレクトリは、呼び出し時に $SKILL_DIR として提供されます。

高速なキーワード検索：

node $SKILL_DIR/scripts/runtime.js --search "keyword"

カスタムクエリ：

1. たとえば /tmp/q.mjs などの一時ファイルに、範囲を限定した JS クエリを書きます。

2. 次を実行します。

   node $SKILL_DIR/scripts/runtime.js --query /tmp/q.mjs
   

3. JSON の標準出力を解析し、簡潔な根拠を示して回答します。

クエリファイルは (async () => { ... })() 内で実行されます。JSON を出力するには return を使用してください。クエリスクリプトは読み取り専用です。remember() と forget() は使用できず、sql() は読み取り専用の SELECT/WITH クエリのみ受け付けます。

最初に行う基本的な処理

生の SQL ではなく、ヘルパーから始めてください。タスクで Obelisk に対して初めてクエリを実行する際は、ユーザーが正確な session_id、メッセージの uuid、または絶対ファイルパスをすでに指定している場合を除き、通常は overview({ limit: 6 }) を呼び出します。

意味的な検索や統合を行うタスクでは、詳細な確認が必要か判断する前に、全体像の把握、メモリの想起、生のセッションに基づく根拠を組み合わせてください。

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 }),
};

sql() は、ヘルパーでは明確に表現できない正確な結合、集計、スキーマに関する質問のためのエスカレーション手段としてのみ使用してください。広範な検索に対する汎用的な代替手段として、生の SQL を使用しないでください。

意図に基づくルーティング

Obelisk は /obelisk の後に指定する、シンプルな意図プレフィックスレイヤーをサポートしています。これは出力の意図を指定するものであり、検索アーキテクチャを指定するものではありません。

意図	説明	リファレンス
recap [target]	アプリへの引き継ぎや共有形式の出力に使う、週次／月次のまとめカードの内容を生成します。	references/recap/overview.md

ルーティングルール：

1. 最初の単語が recap の場合は、最初のクエリを実行する前に references/recap/overview.md を読みます。recap より後のすべての内容が、まとめの対象です。アプリが生成する一般的なプロンプトには、/obelisk recap this week、/obelisk recap last week、/obelisk recap this month、/obelisk recap last month などがあります。これらは、現在の日付とタイムゾーンを基準にした自然な期間指定として解釈してください。
2. recap は独立した検索レイヤーを作成しません。引き続き overview()、memories()、ヘルパーを使用し、必要な場合にのみ sql() を使用します。
3. overview に記載されたカードごとの手順に従ってください。各カードには、それぞれ独自の検索パターンと執筆ファイルがあります。そのカードの根拠を取得し、執筆ファイルを読み、JSON を更新してから、次のカードに進んでください。現在のカードの作成が完了する前に、まとめに関するすべてのリファレンスを先読みしないでください。
4. 最初の単語が recap でない場合は、references/recap/overview.md を読み込まないでください。以下の「クエリのルーティング」に進んでください。週次／月次の要約、チャート、ランキング、共有可能なカード、プレイリスト形式の比喩を含む広範な依頼から、recap を推測しないでください。

リファレンスマップ

習慣ではなく、目的に応じてリファレンスを使ってください。

リファレンス	使用する場面
references/query-patterns.md	幅広い情報の統合、進捗の要約、設計の履歴、週次・月次レビュー、承認済みのメモリ書き込み／アーカイブ／更新スクリプト、またはユーザーが何をしたか、学んだか、決めたか、試したか、やめたかに関する質問。
references/retrieval-semantics.md	複数ステップの検索、プロジェクト／ファイル／セッションをスコープ指定した検索、またはスコープ／成果物／意味上の境界がクエリ設計に影響する場合。
references/schema.md	複雑な sql() を書く前の、SQL のフィールドと結合に関する簡易リファレンス。
references/api-reference.md	ヘルパーのシグネチャ、オプション名、戻り値のフィールド、または remember()／forget() の正確なパラメーターの詳細が不明な場合。
references/pitfalls.md	エラーからの復旧、FTS 構文、エイリアス、並べ替え、行の形式に関する予想外の動作、または簡潔な形式と raw 形式のトレードオフについて。
references/recap/overview.md	明示的な /obelisk recap ... リクエストのみ。

クエリの振り分け

クエリを書く前に、タスクを分類してください。段階的な情報開示は有用ですが、関連するリファレンスを読み飛ばすと、通常はクエリの実行回数が増えます。

• 幅広い情報の統合、進捗の要約、設計の履歴、通常の週次・月次レビュー、またはユーザーが何をしたか、学んだか、決めたか、試したか、やめたかを尋ねる場合は、最初のクエリを実行する前に references/query-patterns.md を読んでください。まず初回または一括の情報統合パターンを使い、必要に応じてファセットごとの詳細確認を行ってください。
• 複数ステップの検索、プロジェクト／ファイル／セッションをスコープ指定した検索、または統合／結論／履歴に関する質問では、事前に references/retrieval-semantics.md を読んでください。このリファレンスでは、クエリ設計の枠組みを定義しています。
• raw sql() を使う前に、必要なテーブルと列の関係がここで明示されている場合を除き、references/schema.md を読んでください。意図的に短く、SQL に焦点を絞っています。列が見つからないエラーが起きた後ではなく、SQL を実行する前に確認してください。幅広い情報の統合では、必要な集計や結合をヘルパーで表現できない場合を除き、raw SQL から始めないでください。
• ヘルパーのオプション名、戻り値のフィールド、スカラー値の省略表記の動作、または remember()／forget() の詳細が不明な場合は、references/api-reference.md を読んでください。
• エラーが発生した後、または FTS 構文、エイリアス、並べ替え、行の形式、簡潔な形式と raw 形式のトレードオフが不明な場合は、references/pitfalls.md を読んでください。

ヘルパーの行形式が不明な場合は、まず小さくスコープを絞ったクエリを実行し、Object.keys(row) または簡潔なサンプルを返してください。フィールド名を推測しないでください。

承認済みのメモリ変更については、まず下記の「メモリレイヤー」セクションに従ってください。 コピーして使える --attune スクリプト（Attune Approved Memory、Forget Approved Memory、Update Approved Memory）には references/query-patterns.md を、正確なパラメーターの仕様には references/api-reference.md のみを使ってください。

コア API

search(text, opts?)

メインメッセージ、サブエージェントのメッセージ、ワークフローエージェントの メッセージを対象に、全文検索を行います。

戻り値：

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

ここでのcontextは、同じセッション内でタイムスタンプが近いメッセージ、つまり時間的に隣接するメッセージを意味します。親子関係の連鎖ではありません。因果関係や親子関係をたどるコンテキストを取得するには、context(uuid)またはtrace(uuid)を使用してください。

エビデンスの境界を保つため、message.content_typeを使用してください。 textはユーザーまたはアシスタントに表示される言語、thinkingはトレースやデバッグ用の情報です。 tool_useはツール呼び出しのメッセージを示し、その詳細はtool_callsに格納されています。tool_resultはツールの実行結果を示し、その詳細はtool_resultsに格納されています。 unknownは保守的なフォールバックです。thinkingを、ユーザーに表示されるアシスタントの結論として扱わないでください。実際のユーザー入力はtype='user'かつcontent_type='text'です。別個のuser_message content typeを作らないでください。

message.is_metaを使用すると、トランスクリプトの制御プレーン情報と会話のエビデンスを区別できます。is_meta=1は、注入された注意書き、コマンドのエンベロープ、その他、ユーザーロールのコンテンツとしてトランスクリプトに含まれていても、デフォルトではユーザーのリクエストとして扱うべきでないメッセージを示します。includeMeta: trueを渡さない限り、search()とthread()はメタメッセージを除外します。context()とtrace()は元の連鎖を保持し、行にis_metaを表示します。

オプション：{ limit, sessionId, project, after, before, cwd, source, includeMeta }。

projectは sessions.projectに対するSQLのLIKEフィルターであり、プロジェクトのIDを完全一致で照合するものではありません。結果はすでにFTS5のランク順に並んでおり、ランクが低いものほど先に表示されます。FTS5のセマンティクスを意図的に利用する場合を除き、数値のランクを手動で解釈するより、返された順序を優先してください。

sourceには'claude'、'codex'を指定できます。省略すると、インデックス済みのすべてのソースが検索対象になります。

context(uuid)

インデックス済みの1つのメッセージを中心とした全体像を返します。

{ message, parentChain, session, subagent, workflow }

search()で有望なメッセージが見つかった後に使用してください。セッション全体を出力せずに、1つのエビデンスから縦方向に展開するための一般的な方法です。

sql(query, ...params)

?プレースホルダーを使用する、読み取り専用のSQL SELECT/WITHです。行の配列を返します。SQLは、ヘルパー優先のインターフェースでは不十分な場合に、正確な構造化結合や集計を行うための代替手段です。デフォルトの検索開始点ではありません。

複雑なSQLを書く前に、references/schema.mdを読んでください。これは、SQLのフィールドと結合をすばやく確認するためのリファレンスです。実行可能なDDLはscripts/schema.sqlにあります。ソースとの整合性を確認する場合にのみ、このSQLファイルを使用してください。一般的に安全な結合方法：

• tool_callsにはタイムスタンプがありません。messages m ON m.uuid = tc.message_uuidで結合してください。
• tool_resultsにはタイムスタンプがありません。messages m ON m.uuid = tr.message_uuidで結合してください。
• プロジェクトやセッションで絞り込む場合は、sessions s ON s.id = <table>.session_idで結合してください。
• 最終回答で手作業による件数の集計を行うより、SQL側でGROUP BY、COUNT、MAX、ORDER BY、LIMITを使用してください。

テーブル：sessions、messages、tool_calls、tool_results、summaries、 memories、subagents、workflows、workflow_agents、messages_fts。

構造化ヘルパー

これらのヘルパーは、同じ SQLite 構造に対する便利なアクセサーです。sql() の代わりにはなりませんが、まず最初に使うための標準的なインターフェースです。ヘルパーで利用できない正確な集計や結合が必要な場合は、sql() を使用してください。

すべてのリストヘルパーは、上限を指定する limit を受け付けます。また、多くのヘルパーは次のオプションも受け付けます。 { project, after, before, sessionId, sessions, branch, source }。一般的でないフィルターや戻り値のフィールドを利用する前に、references/api-reference.md または簡単なサンプルを確認してください。

• overview(opts?) -- 概要を把握するための簡潔なマップです。判別できる場合は現在の cwd／プロジェクト、プロジェクトとソースの全体件数、現在のプロジェクトにおける最近のセッションとメモリレコードを返します。これはマップであり、証拠ではありません。
• sessions(opts?) -- セッションの行を新しい順に返します。project は SQL の LIKE パターンです。
• recent(n?) -- 最近のセッションを取得するための短縮形です。
• summaries(opts?) -- サマリーの行を新しい順に返します：{ id, session_id, timestamp, source, content, session_title, project }。ここでの source はサマリーの種類であり、トランスクリプトのプロバイダーではありません。
• subagents(opts?) -- messageCount を含むサブエージェントのメタデータです。
• workflows(opts?) -- ワークフローの実行を新しい順に返します。
• workflowTree(runId) -- ワークフローの行に、解析済みの result と agents を加えて返します。容量の大きい script や result_json が含まれる場合があるため、必要なフィールドだけを取得してください。
• fileHistory(filePath, opts?) -- ファイルに対する Read／Edit／Write ツール呼び出しを古い順に返します。多数の Read 行を含みます。
• failures(opts?) -- ツールとセッションのコンテキストを含む、失敗したツールの結果を新しい順に返します。
• trace(uuid) -- ルートからメッセージまでの親チェーンです。
• thread(sessionId, opts?) -- セッションのメッセージをタイムスタンプ順に返します。デフォルトではメタメッセージを除外します。挿入されたコンテキストやコマンドのエンベロープを調査する場合は、{ includeMeta: true } を渡してください。
• raw(uuid, opts?) -- 元の JSONL 行にウィンドウ形式でアクセスします。
• memories(opts?) -- メモリの想起レイヤーです。opts：{ query, project, sessionId, sessions, after, before, branch, limit }。query を指定しない場合は、有効なメモリレコードを新しい順に返します。query を指定した場合は、安全な FTS5 トークン化を通じて summary／path を検索し、rank を返します。rank の値が小さいものほど先に並びます。レコードには、ファイルなどの明示的な想起対象を示す、NULL 可能な JSON の anchors が含まれる場合があります。完全な内容を確認するには、path のファイルを読み取ってください。

検索契約

クエリの対象範囲を絞り、上限を設け、構造に基づいて検索します。

• まず範囲を定める：ロケーターをスコープ、アーティファクト、セマンティックのいずれかに分類します。FTS を使う前に、最も狭い構造的ロケーターを使用します。ユーザーから範囲を広げるよう求められていない限り、スコープ内の結果が空でも問題ありません。
• まず全体像を把握する：新しいタスクでは、ユーザーがセッション／メッセージ／ファイルの正確なロケーターを指定していない限り、通常は詳細検索の前に overview({ limit: 6 }) を呼び出します。これはナビゲーション用の地図です。事実は memories()、search()、ヘルパー、必要な場合に限り sql() で確認します。
• まずヘルパーを使う：初回の検索では overview()、memories()、search()、sessions()、summaries()、fileHistory() などのヘルパーを優先します。必要な結合、グループ化、またはスキーマレベルの厳密な確認をヘルパーで表現できない場合に限り、生の sql() に切り替えます。
• プローブの前に計画する：結論、広範な履歴、障害調査、またはファイルの変遷を調べる場合は、中間結果を何度も確認する代わりに、上限を設けた検索スクリプトを作成します。
• テキストより構造を優先する：件数の計算、結合、グループ化、重複排除、射影は SQL または JS で行います。実行時の JSON はコンパクトに保ち、統合タスクでは理想的には 10k～12k 文字未満にします。
• 結論より証拠を優先する：安定した ID（session_id、uuid、tool_call_id、run_id、agent_id）と短い抜粋を含む、コンパクトな証拠を返してから、最終回答で統合します。
• デフォルトではメタデータを除外する：is_meta=1 の行は注入された制御プレーンのトランスクリプト情報です。ヘルパーはデフォルトでこれらを非表示にします。通常の会話の証拠を生の SQL で検索する場合は、メタ行が調査対象でない限り COALESCE(m.is_meta,0)=0 を含めます。
• 長期的に有用な結論を保存する：回答後、検索によって今後のセッションで再利用される可能性の高い長期的な結論が得られ、memories() にまだ記録されていない場合は、メモリーへの書き込みを明示的に提案します。提案は簡潔にします。ユーザーの承認を得るまでは、Markdown ファイルを書き込んだり --attune を実行したりしないでください。

フィールド、コンテキスト、並び順、FTS、またはヘルパーのセマンティクスがクエリに影響する場合は、コーディングの前に references/retrieval-semantics.md を読みます。クエリでエラーが発生した場合は、再試行する前に references/pitfalls.md を読みます。

メモリーレイヤー

Obelisk には、生のセッションデータと並行して永続的なメモリーレイヤーがあります。検索のたびに両方のレイヤーを照会します。過去の結論には memories() を、生のセッションの証拠には search() とヘルパーを使います。メモリーは過去の記録として扱い、最終的な根拠にはしません。メモリーレコードが回答に影響する場合は、以前に記録された内容であることを自然に伝え、正確さが重要な場合は生のセッションの証拠と照合します。生のセッションデータは証拠のレイヤーですが、1 件の検索結果だけで全容が明らかになるわけではありません。検索し、簡潔に引用します。

メモリーレイヤーは英語で索引付けされています。ユーザーが別の言語で質問しても、memories({ query }) には英語の用語を使います。現在の会話の言語にかかわらず、すべての remember().summary は英語で記述します。ランタイムは保護策として、メモリーのクエリと要約に明らかな CJK テキストが含まれている場合、それを拒否します。

想起： memories({ query: 'English topic terms', project: '...' }) を使って、現在のタスクに関連する過去の結論を検索します。ユーザーの依頼が英語以外の場合は、memories() を呼び出す前に、簡潔な英語の検索語に翻訳します。メモリーの想起では、summary と path に対して安全な FTS5 トークン化を使用するため、ハイフンや句読点がそのまま MATCH 構文エラーの原因になることはありません。他のリストヘルパーと同様、文字列を渡すと sessionId として扱われ、数値を渡すと limit として扱われます。全文を確認するには、path のファイルを読みます。memories() が返すのは有効なメモリーのみです。アーカイブされたメモリーは管理／監査データであり、想起の対象ではありません。

メモリーに適した候補には、設計上の決定事項、プロジェクトの規約、採用されなかった代替案、繰り返し発生する障害の原因、ワークフローのパターン、生の証拠を複数照合して導いた結論などがあります。1 回限りの検索、不確かな調査結果、既存のメモリーですでに網羅されている結論については、メモリーへの保存を提案しないでください。 メモリ変更の承認： 現在の回答でメモリを使うかどうかの判断はエージェントが行い、承認は不要です。永続メモリの変更には承認が必要です。 ユーザーがメモリは間違っている、古くなっている、忘れるべき、または別の内容にすべきだと明示した場合、その依頼を該当するメモリのアーカイブまたは更新の承認とします。複数のメモリが該当する可能性がある場合を除き、二度目の確認は求めないでください。自分で競合の可能性に気づいた場合は、簡潔に説明してからメモリの状態を変更する前に確認してください。

メモリの書き込み： 検索によって保存する価値のある結論が得られたら、メモリファイルの書き込みを提案します。ユーザーの承認が必要です。手順：

1. Write ツールを使って Markdown ファイルを書き込みます（ユーザーが承認）。
2. 範囲を絞ったメモリ登録スクリプトで remember() を使って登録します。

return remember({
  path: '.obelisk/memories/design-decision-x.md',
  session_id: 'current-session-id',
  message_start: 'uuid-of-first-relevant-msg',
  message_end: 'uuid-of-last-relevant-msg',
  anchors: [{ kind: 'file', path: 'src/path/to/file.ts' }],
  summary: 'Detailed summary: what was decided, why, what alternatives were considered, and what constraints drove the choice.'
})

次のコマンドで登録スクリプトを実行します。

node $SKILL_DIR/scripts/runtime.js --attune /tmp/register-memory.mjs

--attune で公開されるのは、メモリ変更用ヘルパーの remember() と forget() のみです。search()、sql()、memories() などの検索用ヘルパーは公開されません。ソース ID やメモリ ID が必要な場合は、通常の --query スクリプトで先に確認してください。

remember() は path がすでに存在し、ファイルを指していることを検証します。session_id が指定されている場合、相対パスはソースセッションの project_path を基準に解決され、その後、正規化された絶対パスとして保存されます。session_id と .obelisk/memories/... のようなプロジェクト相対パスを使用してください。 省略可能な anchors はオブジェクトの配列である必要があり、NULL 許容の JSON テキストとして保存されます。メモリに関連付けられたファイルなど、明示的な想起対象にのみ使用してください。

summary は英語で記述し、ファイルを読まなくても memories() の結果だけで関連性を判断できるだけの詳細を含めてください。タイトルだけでなく、判断、その理由、主要な制約を含めてください。

message_start／message_end の範囲は、この結論が会話のどこで導かれたかを示します。後で元の根拠をたどるために使用してください。

メモリの削除： ユーザーがメモリは古くなっている、間違っている、または忘れるべきだと言った場合は、通常の検索を先に行い、該当する正確なメモリ ID を特定してください。明確な候補が一つだけなら、ユーザーの依頼をアーカイブの承認とします。複数のメモリが該当する可能性がある場合は、どれを忘れるべきか尋ねてください。その後、--attune スクリプトを実行します。

return forget({
  id: 'mem-id-to-delete',
  reason: 'Outdated by newer project guidance.',
});

forget() は deleted_at と deleted_reason を設定してメモリレコードをアーカイブします。アクティブな検索対象からレコードを除外しますが、Markdown ファイルは削除しません。メモリレコードはインデックスの再構築後も保持され、自動的に変更されることはありません。

メモリの更新： メモリの更新は、ユーザーが承認する一つの操作です。forget() で古いメモリをアーカイブし、その後、置き換えとなる Markdown メモリを書き込んで remember() で登録します。ユーザーがメモリを明示的に訂正した場合、その訂正をアーカイブと書き込みを組み合わせた手順の承認とします。不一致を自分で見つけた場合は、先に確認してください。

最小限のパターン

検索してから、有望な結果を一つ展開します。

const hits = search('auth fix', { limit: 5 });
if (!hits.length) return [];
return hits.slice(0, 3).map(h => ({
  session_id: h.session.id,
  session_title: h.session.title,
  uuid: h.message.uuid,
  snippet: h.message.text?.slice(0, 240),
}));

名前を決めつける前にヘルパーのフィールドを確認します。

const rows = summaries({ project: '%quiet-zero%', limit: 1 });
return rows.length ? Object.keys(rows[0]) : [];

スレッド全体を取得せずに、前後のメッセージを取得します。

const hit = search('runtime query', { limit: 1 })[0];
return sql(
  `SELECT uuid, role, timestamp, substr(text,1,240) AS snippet
   FROM messages
   WHERE session_id=? AND timestamp>=?
   ORDER BY timestamp LIMIT 6`,
  hit.session.id,
  hit.message.timestamp
);

より詳しい手順については、references/query-patterns.md を参照してください。

注記

• 初回実行時にインデックスが構築されます。以降の実行では差分のみ更新されます。
• DB の場所：~/.obelisk/obelisk.sqlite。必要に応じて、以前の ~/.claude/obelisk.sqlite が引き継がれます。
• クエリスクリプトはサンドボックス化された VM で実行され、スクリプト内からファイルシステムやネットワークにアクセスできません。
• インデックス化されたテキストと保存されたツールの入力／結果は、10k 文字で切り詰められます。特定の JSONL 範囲には raw(uuid, { offset, limit }) を使用してください。