session-indexer icon

session-indexer

session-indexer 是一款命令列工具,可搜尋單一專案中的 Claude Code session 歷史。它將 JSONL 逐字稿儲存在每專案 SQLite 資料庫中,並使用 Ollama embeddings;在無法進行向量搜尋時則以 FTS5/BM25 作為備援。

session-indexer

總覽

session-indexer 是一款命令列工具,可針對 Claude Code session 歷史進行每專案語意搜尋。它將 JSONL 逐字稿轉成以 SQLite 為後端的儲存區,讓開發者能依語意而非精確關鍵字來搜尋較早的 sessions。

此專案設計給一位開發者在一台機器上使用,並將每個專案隔離在各自的 .claude/sessions.db 檔案中。README 說明它可以自動索引已完成的 sessions、在新 session 開始時擷取相關的先前脈絡,並在透過 Ollama 的向量 embeddings 無法使用時回退到 FTS5。

功能

每專案 SQLite session 儲存區

將 Claude Code 的 JSONL session 逐字稿索引到儲存在專案 .claude/ 目錄下的每專案 SQLite 資料庫中。README 將此流程描述為 append-only 且具冪等性,因此重新執行 mine 可由可用逐字稿重建專案資料庫。

以 embeddings 進行語意擷取

使用透過 Ollama 的 bge-m3 embeddings,以語意相似度搜尋過去的 sessions。這是為了回答像是先前工作中做了什麼決定之類的問題,而不依賴精確關鍵字比對。

關鍵字備援搜尋

當向量 embeddings 不可用時,改以 SQLite FTS5/BM25 作為備援。README 指出兩種擷取模式下分數越高越好;embeddings 使用 cosine similarity,而備援搜尋則使用反向的 BM25 rank。

自動 session 開始脈絡

在新 session 開始時,自動注入相關的過去脈絡。專案將此描述為一種與目前 Git branch 和最近 commits 綁定的 hook-based 工作流程。

事實萃取與 supersession

包含獨立的 facts 層,用於從已索引的 chunks 中萃取持久的 subject-predicate-object facts。Facts 是手動建立的,而非由 Stop hook 建立;README 也描述了 supersession 保護與信心門檻。

命令列工作流程

提供多個 CLI 指令,用於索引、搜尋、列出、顯示與檢查 sessions 和 facts。README 的範例包含 search、embed、stats、distill、facts search 與 facts supersede。

使用情境

  • 重新查看先前的決策

    在返回一個仍在進行中的程式碼庫後,想回想先前 Claude Code sessions 中做了哪些決定時使用。此工具適合跨越多個 sessions 的問題,例如設計選擇、除錯步驟或實作方向。

  • 在新 session 開始時載入脈絡

    在某個分支上繼續工作前,使用 session-start hook 載入相關的先前脈絡。當專案歷史很長,而下一個 session 應該從目前最重要內容的摘要開始時,這特別有用。

  • 按需搜尋歷史

    當你想直接從終端機或 Claude Code 內部使用 /recall 來檢視歷史時,可執行手動搜尋指令。這提供一種不用逐一瀏覽逐字稿就能找到特定討論的方法。

  • 萃取持久的專案事實

    當原始逐字稿過於雜訊化,而你需要可在之後查詢的持久陳述時,使用 facts 層。README 將其定位為一個獨立、手動觸發的步驟,用來從已索引的 chunks 中萃取穩定的 facts。

  • 保持專案記憶彼此分離

    當你希望某個專案的記憶與另一個專案彼此隔離時,使用每專案資料庫。README 強調每個專案都有自己的本機儲存區,因此一個專案的 session 歷史不會影響另一個專案。

Pros and Cons

Pros

  • 將每個專案的歷史分開儲存在本機 SQLite 資料庫中。
  • 支援對過去 Claude Code sessions 的語意搜尋,比精確比對查找更有彈性。
  • 在新 session 開始時可自動帶出相關的先前脈絡。
  • 包含可手動操作的 facts 層,不只是原始逐字稿搜尋。
  • 提供用於索引、搜尋、列出與檢查 session 歷史的 CLI 指令。

Cons

  • 這個工具刻意只針對單一開發者與單一機器設計,因此不是共享的團隊記憶系統。
  • 若要使用主要擷取模式,向量搜尋依賴 Ollama 與 bge-m3 模型;若沒有它,專案則使用 FTS5/BM25 備援。

FAQ

這是給個人使用還是給整個團隊的記憶系統?

它是為單一開發者、單一機器而設計。README 明確說明,它會在專案中索引一個人的 Claude Code session,而不是共享的團隊歷史或多使用者儲存區。

要怎麼在 Claude Code 專案中設定?

核心流程是先建置並安裝二進位檔,視需要拉取 Ollama embedding 模型,加入專案 hooks,然後讓 Stop hook 將已完成的 sessions 索引到專案的 .claude/sessions.db 檔案中。

我可以手動搜尋 session 歷史嗎?

可以。README 顯示了手動搜尋指令,也提到可在 Claude Code 內使用 /recall skill 進行查詢。

如果沒有 embeddings 會怎樣?

README 將透過 Ollama 使用 bge-m3 embeddings 描述為主要檢索模式,而當 embeddings 不可用時,則使用 FTS5 BM25 備援。

這個工具可處理哪些類型的輸出?

此倉庫包含 architecture 文件與 use-cases 文件,而且工具可以索引 sessions、搜尋歷史、提煉 facts、列出 sessions,並檢視已儲存的 chunks。

Quick Facts

類別
開發者工具
產品類型
命令列 session 索引器
主要用途
搜尋 Claude Code session 歷史
儲存方式
每專案 SQLite 資料庫
擷取模式
Ollama embeddings 搭配 FTS5 備援
來源網域
github.com