pensieve

Pensieve

セッションをまたいで残る、エージェント主導の個人用メモリです。

毎日 AI アシスタント（Claude Code）と話していても、セッションが終わるとすべて忘れてしまいます。Pensieve は、あなたが管理する長期メモリです。会話中のいつでも、*「これを pensieve に追加して」と言えば何かを記録でき、「X について何を知っている？」*と尋ねれば、それを呼び戻せます。情報は整理され、最新の状態で、あなたのものとしてそこにあります。

たとえるなら、思考のひと筋を意識して引き出し、あとで見返せるよう器に収めることです。

これは小さな Python + SQLite エンジンで、2 つの入口を備えています。エージェントが使う MCP サーバーと、あなたが使う CLI です。メモリは ~/.pensieve という単一のファイルに保存されます。

---

哲学

Pensieve のあらゆる判断を形作る 5 つの考え方：

1. プロジェクト管理ツールではなく、情報の湖です。 あなたが知っていることを保存し、思い出せるようにします。タスク、ステータス、期限は意図的に設けていません。エージェントは読み取ることで状態を推測し、ストアは情報を保持するだけです。

2. 記録も呼び出しも、明示的に行います。 Pensieve が自ら動くことはありません。*「これを覚えておいて」*と言われたときだけ記録し、尋ねられたときだけ呼び出します。ひそかな保存も、セッション開始時のメモリの自動読み込みもありません。何を記録し、何を取り出すかは、あなたが管理できます。

3. 構造は自然に生まれます。最初から設計する必要はありません。 分類体系を作る必要はありません。実際に取り組んでいる分野を表すトップレベルのストリームをいくつか用意して、そこにメモを追加します。メモに登場する人、組織、トピックは自動的にエンティティになり、何度も登場するものは独立したスレッドになります。整理は、使うことで生まれる結果です。

4. メモが基本単位で、それ以外はすべてメモを参照します。 1 つのメモだけで完結させることも、複数のストリームに置くこともできます。エンティティとスレッドはメモのビューであり、メモの所有者ではありません。そのため、トピックを削除しても、別の内容にも関係するメモが失われることはありません。

5. 世界を指し示し、コピーしないでください。 リポジトリ、ファイル、URL をアセットとして添付します。アセットは参照先へのポインターで、「使い方」のひとことを添えられます。Pensieve はポインターを保存し、必要なときに読み取ります。ディスクをクロールしたり、リンクを自らたどったりすることはありません。

その背景にある考えを詳しく知りたいですか？設計上の判断、モデル全体、トレードオフについては、 docs/philosophy.mdをご覧ください。

---

モデル

対象	内容
ストリーム	仕事や生活におけるトップレベルの領域です。career、personal、side-projects など。意識して少数に保ちます。
メモ	記録する情報の最小単位です。複数のストリームに置くことができます。
エンティティ	メモが扱っている人物、組織、トピックです。メモへのタグ付けによって生まれ、単独で作成されることはありません。
スレッド	何度も登場し、ストリーム内の独立したトピックとして扱う価値が生まれたエンティティです。
アセット	参照先へのポインター（リポジトリ／ファイル／ディレクトリ／URL／画像／ドキュメント）と使用方法のヒントです。ストリーム、スレッド、またはメモに添付します。

呼び出しには 3 つの方法があります。 名前から（find）、内容から（search — 全文検索、語幹処理、順位付け）、時間から（recent — 最近の変更内容）。

---

インストール

Python 3.12 以降が必要です。

推奨：PyPI からインストール

Pensieve は標準的な MCP サーバーなので、手早く始めるには pipx （または uv）を使います。

pipx install pensieve-mcp     # or: uv tool install pensieve-mcp

これにより、pensieve（CLI）と pensieve-mcp（MCP サーバー）が PATH に追加されます。次に、エージェントから接続します。Claude Code の場合：

claude mcp add --scope user pensieve -- pensieve-mcp

ほかの MCP クライアントでは、pensieve-mcp コマンドを stdio サーバーとして登録します。インストールせずにその場で実行する場合は、uvx pensieve-mcp も使えます。

Pensieve は公式の MCP Registry に io.github.praveen-ilangovan/pensieve として登録されているため、レジストリに対応したクライアントから直接検出してインストールできます。

注： PyPI パッケージはエンジン（CLI と MCP サーバー）です。判断機能を担う Claude のスキル（capture／fetch のフロー）はホイールではなくリポジトリに含まれています。利用する場合は、以下のスクリプトでインストールしてください。スキルが ~/.claude/skills/pensieve/ に配置されます。

ソースからエージェントをセットアップする

git clone [email protected]:praveen-ilangovan/pensieve.git
cd pensieve
./install.sh          # Claude Code (backward-compatible default)
./install.sh codex    # Codex
./install.sh all      # both

install.sh は最初に前提条件を確認し（不足しているものがあれば何も変更しません）、pipx があることを確認してから、Pensieve をインストールし（pensieve と pensieve-mcp が PATH に追加されます）、選択したエージェントのスキルをインストールし、そのエージェントのユーザー設定に MCP サーバーを登録します。Claude のスキルは ~/.claude/skills/pensieve/ に配置されます。Codex のユーザー単位の $pensieve スキルは ~/.agents/skills/pensieve/ にシンボリックリンクされるため、すべてのリポジトリで利用できます。冪等なので、更新を取り込むためにいつでも再実行できます。

Codex の MCP 登録では PENSIEVE_HOME=~/.pensieve を固定するため、Codex をこのリポジトリから起動した場合（このリポジトリの .env は意図的に開発コマンドを .local/manual に向けています）も、Codex は Claude と同じ個人用ストアを読み書きします。エンジンと MCP ツールに変更はありません。Codex のスキルが、既存の Claude アダプターと同じ、意図的な記録・想起の規律を提供します。

次に選択したエージェントを再起動し、任意のディレクトリから次のように尋ねます。

「どんなストリームがある？ pensieve を確認して」

メモリは ~/.pensieve に保存されます。

---

使い方（エージェントと一緒に）

Pensieve の真価はエージェントとの連携で発揮されます。自然な言葉で話しかけると、エージェントが判断してツールを呼び出します。以下はすべて、Claude Code に話しかけるだけです。

ドメインを設定する（最初に一度だけ、意図的に行います）。

「仕事探しと仕事のために、Career という pensieve ストリームを作成して」

記録する — 残しておく価値のあることがあったら、いつでも行います。

「これを pensieve に追加して：Maya とプラットフォーム職について話した。彼女が私のポートフォリオを確認している」

エージェントは、何が長く役立つ情報かを見極め、適切なストリームに振り分け、「Maya」が追跡する価値のある人物だと認識します。こうした作業をあなたが管理する必要はありません。たとえば、ある話題が career と side-project の両方に関係するなど、メモが二つのドメインにまたがる場合は、メモを両方に一つずつではなく一件保存します。

思い出す — 質問に合った切り口を選びます。

「Maya について何を知ってる？」・「給与について何を決めた？」・「最近の変化をまとめて教えて」

リアルタイムのコンテキストを示す — エージェントがどこを読めばよいか分かるようにします。

「~/projects/acme にあるプロジェクトリポジトリを side-projects ストリームのアセットとして追加して。ヒント：まず README.md を読んで。」後で、「acme リポジトリを開いて」と頼みます。（頼まれた場合にのみ、その参照先をたどります。）

昇格する — 同じことが繰り返し登場すると、エージェントが提案します。

「Maya は5件のメモに出てきてる。Career の下に専用のスレッドを作る？」

削除／復元する — すべてソフト削除なので、元に戻せます。

「そのメモを削除して。」／「やっぱり、元に戻して。」／「X ストリームはもう使わない。」

---

使い方（CLI）

同じエンジンは CLI としても使えます。エージェントを使わずに手早く確認したり、スクリプトから操作したりするときに便利です（pensieve stream list、pensieve search "…" など）。使用例付きの全コマンドリファレンス： docs/cli.md。

---

仕組み（内部の動作）

• SQLite ストア（~/.pensieve）。初回使用時に Alembic を通じて自動でマイグレーションされます。
• SQLite FTS5 と porter ステマーによる全文検索（「pricing」で検索すると「priced」も見つかります）。
• すっきりとしたポート／アダプター構成のコアです。サービスはストレージの ポート に依存し、互換性のある 2 種類のバックエンド（SQLite とインメモリの代替実装）を切り替えて使えます。適合性テストによって、両者の整合性を保っています。
• MCP サーバーとCLIは薄い「オペレーション」レイヤーです。何を保持するか、エンティティをどう解決するか、いつ昇格するかといった 判断 は、エージェントのスキル（adapters/claude/）にあります。

---

開発する

make install         # poetry env + pre-commit hooks
make test            # unit + integration
make eval            # deterministic engine evaluators
make check           # ruff (lint+format) + mypy
make manual ARGS="stream list"   # run the CLI against the local dev store

このリポジトリは自己完結型の開発環境であり、実際の ~/.pensieve に触れることはありません。リポジトリ内の MCP サーバーと CLI はローカルの開発用ストア（.env → .local/manual）を使用します。グローバルインストール（./install.sh）が ~/.pensieve を参照します。

設計メモは plans/（スライスごとに 1 ファイルと、plans/roadmap.md）および docs/ にあります（philosophy.md — 理由とモデル、cli.md — コマンド）。

---

ステータス

ストリーム · スレッド · ノート · エンティティ · 昇格 · アセット · 検索 · 新しさ · 複数ストリームのノート · ソフト削除／復元が、CLI と MCP の両方から利用でき、実用されて日々使われています。実際のエージェントを使い、スライスごとに構築・検証しました。次の予定については plans/roadmap.md をご覧ください。