Lorekeeper

Lorekeeper

AI エージェントのための自己改善型メモリ。コマンドひとつで、クラウド不要、設定不要。

pip install lorekeeper-mcp && lorekeeper setup && lorekeeper

エージェントはセッションをまたいで記憶し、そのメモリは増えるだけでなく、より良くなっていきます。 ローカルで動作します。API キー不要。サインアップ不要。永久に無料で利用できます。

---

Lorekeeper を選ぶ理由

AI エージェントのセッションは、毎回まっさらな状態で始まります。コンテキストを説明し直し、好みを伝え直し、パターンを教え直す必要があります。毎回です。

CLAUDE.md や .cursorrules のようなファイルは役立ちますが、手作業で管理する必要があり、自分自身を検索できず、内容も古くなります。クラウドサービスは便利ですが、セッションデータが手元のマシンから外部に送信され、API 呼び出しごとに料金がかかります。ライブラリは高機能ですが、連携を自分で実装しなければなりません。

Lorekeeper は、これらとは異なる形をしています。**一度 pip install するだけで使えるローカル MCP サーバーです。**既存のエージェントに接続し、メモリを自分のディスク上の SQLite に保存して、セッションを重ねるごとに改善していきます。

Agent uses a memory → rates it useful or not →
scores adjust automatically → weak memories decay →
strong memories surface more often → search gets sharper

インストール直後の状態と、6 か月使い続けた状態では、**まったく異なる製品と言えるほど変わります。**使い続けるほど不要な情報が減り、エージェントがコードベースを本当に理解しているように感じられるようになります。

---

クイックスタート

3 分で始められ、設定は不要です。

# 1. Install
pip install lorekeeper-mcp

# 2. Configure your agents (auto-detects Hermes, Claude Code, Cursor)
lorekeeper setup

# 3. Start the MCP server
lorekeeper

lorekeeper setup はインストール済みのエージェントを検出し、MCP エントリ、エージェントプロンプト、同梱スキルを自動的に追加します。書き込みを行わずにプレビューするには --check を使います。インストールを確認するには lorekeeper --help または lorekeeper --version を実行してください。

次に、エージェントにこう尋ねてみてください。

「エンドポイントのデバッグには curl -vX GET を使うのが好みだと覚えておいてください。」

エージェントは lore_remember を呼び出し、メモリが保存されます。次のセッションでは、こう尋ねます。

「私が好んで使うデバッグコマンドは何ですか？」

エージェントは lore_search を呼び出し、メモリを取得します。✅

詳しい手順 → docs/quickstart.md

---

機能

機能	説明
ハイブリッド検索	セマンティックベクトル＋BM25 キーワード＋時間経過による減衰＋使用頻度＋メモリスコアを、重み付けされた数式ですべて順位付けします
自己改善	lore_update のフィードバックでスコアを調整します。質の低いメモリは薄れていきます（信頼度が 2 未満で、役に立たない場合はソフト削除）。質の高いメモリは上位に表示されます。
自動リンク	新しいメモリを、意味的に最も近い既存のメモリに自動的にリンクします。手間をかけずに軽量なナレッジグラフが形成されます。
重複検出	新しいデータを挿入する際、既存のメモリと照合します。ほぼ同一の内容は登録されません（force=true で上書きできます）。
ダッシュボード	すべての機能を備えた Web UI で、閲覧、検索、編集、削除ができます。バックアップ／復元と重複プレビューを含む 7 つのタブがあります。
汎用 MCP	Claude Code、Cursor、Hermes、Copilot、OpenCode など、MCP 互換のあらゆるエージェントで動作します。
ローカル優先	データは手元のマシンに保存されます。SQLite と LanceDB を使用します。クラウド依存なし、API キー不要です。
名前空間	複数のエージェントで、分離された名前空間を使いながら同じストアを共有できます。書き込みは各自の名前空間に行い、読み込みでは共有プールも対象になります。
リフレクション	エージェントがセッションから学びを自動抽出します。発見したことや教訓が、検索可能なメモリになります。

---

ユースケース

セッションをまたいでコンテキストを維持

月曜日に認証レイヤーを設定しました。水曜日、別のエージェントが何も知らない状態で新たに開始します。Lorekeeper があれば、ミドルウェアのパス、トークン形式、エッジケースをカバーするテストをすでに把握しています。一度伝えただけで済むからです。

"Remember that our JWT uses jose middleware in src/middleware/auth.ts
 and refresh tokens expire in 7 days."
→ lore_remember stores it
→ Every future session, on any agent: already in context

1 つのメモリプールを複数のエージェントで共有

レビューには Claude Code、実装には Cursor、計画には Hermes。それぞれがゼロから始める必要はありません。Lorekeeper の名前空間を使えば、1 つのストアを共有できます。あるエージェントが見つけたことは、すべてのエージェントの知識になります。

→ Engineer agent notes a performance quirk in the search service
→ lore_remember stores it under the shared namespace
→ PM agent surfaces it during sprint planning
→ No briefing, no copy-paste

セッションをまたいだデバッグ

3 週間前、エージェントに手伝ってもらいながら、微妙な CORS のバグを修正しました。あなたもエージェントも、詳細を覚えていません。

"What did we figure out about the CORS issue?"
→ lore_search returns the root cause, the fix, and the context around it

プロジェクトへのオンボーディング

新しいリポジトリ、新しいエージェントセッション。アーキテクチャを改めて説明する代わりに、最初のセッションの後で lore_remember を数回呼び出します。次のセッションも、その後のすべてのエージェントも、適切な基盤から始められます。

"Remember: the payment service requires X-Idempotency-Key on all POST requests."
→ Claude Code, Cursor, and Codex all read from the same store

---

対象ユーザー

次に当てはまる方におすすめです：

• Claude Code を使っていて、セッション間でプロジェクトのコンテキストを記憶させたい
• Cursor を使っていて、エージェントのメモリを永続化したい
• Hermes、OpenCode、Codex CLI、Copilot CLI、または MCP 互換のエージェントを使っている
• 複数のエージェントを使っていて、知識を共有させたい

現時点では、次に当てはまる方にはおすすめしません：

• チーム向け RBAC、監査ログ、または SSO が必要（ベータ版終了後に対応予定）
• コンシューマー向け AI アプリを構築している（私たちは API ファーストではなく、エージェントファーストです）
• AI コーディングエージェントを使っていない（Lorekeeper は MCP ツールです）

---

比較

この分野には優れたツールがあり、それぞれ異なるトレードオフを選んでいます。Lorekeeper の位置づけは次のとおりです：

	ファイルベース	クラウドサービス	Docker サーバー	ライブラリ（Mem0）	agentmemory（Node）	Lorekeeper
セットアップ	組み込み	API キー＋クラウド設定	docker compose	統合コードを記述	npx agentmemory	pip install
データ	ローカル	クラウド	ローカル	選択可能	ローカル	ローカル
検索	grep	ベクトル	ベクトル	ベクトル	ハイブリッド	ハイブリッド＋時間減衰＋使用状況＋スコア
自己改善	❌	❌	❌	❌	❌	✅ 品質ループ
ナレッジグラフ	❌	有料	❌	有料	❌	✅ 無料の自動リンク
ダッシュボード	❌	✅	❌	❌	ビューアー	✅ 完全な Web UI
依存関係	なし	約 300MB	約 2GB	約 1.4GB	約 200MB	約 1.4GB（埋め込み）
エージェントによる開発	❌	❌	❌	❌	❌	✅ 毎日実際に活用

クラウドサービスや Docker ベースのソリューションは、チームや本番アプリに適した優れた選択肢です。Lorekeeper はその対極に最適化されています。運用作業なし、クラウドなし、自己改善するストアが何より重要な、個人開発者やエージェントのワークフロー向けです。

依存関係について： 約 1.4GB は、sentence-transformers の埋め込みモデル（PyTorch）によるものです。これは、ローカル埋め込みソリューションであればどれも同程度のサイズです。私たちはその点を正直にお伝えしています。

---

MCP ツール

Lorekeeper は、記憶のライフサイクル全体をカバーする 10 個の MCP ツールを提供します。

ツール	目的
lore_search	関連度スコア付きのセマンティック検索とキーワード検索のハイブリッド
lore_remember	すばやく一度で記憶を保存（タイトルとリンクを自動作成）
lore_insert	カスタムスコアとリンクを指定した、構造化データの一括挿入
lore_update	フィードバックループ — 記憶を評価し、品質を向上
lore_forget	誤った記憶や古くなった記憶を論理削除
lore_reflect	セッション終了時に学びを抽出し、発見を自動保存
lore_processed_sessions	処理済みのセッションを確認
lore_recommend_links	関連する記憶間のリンク候補を提案
lore_get_suggestions	スイープエンジンからの保留中のリンク提案を一覧表示
lore_review_suggestion	1 件以上のリンク提案を承認または却下（一括処理）

API リファレンスの全文 → docs/api-reference.md

---

ダッシュボード

記憶ストアの閲覧、検索、編集、管理を行うためのローカル Web UI です。

lorekeeper-dashboard
# → http://127.0.0.1:7777

7 つのタブ：

タブ	内容
Memories	ライブフィルター付きの並べ替え可能なテーブル — タイトル、スコア、信頼度、使用状況、日付
Detail	記憶の内容の編集、リンクの管理、論理削除または完全削除
Links	ナレッジグラフの閲覧 — ソース → 関係 → ターゲット
Query	結果ごとのスコア内訳を確認できる、セマンティック検索とキーワード検索のアドホック実行
Sessions	学びが抽出された、処理済みのエージェントセッションすべて
Config	検索の重み、品質のしきい値、制限をリアルタイムで調整
Backup	重複のプレビュー付きで、記憶を JSON としてエクスポート／インポート
Suggestions	スイープエンジンが生成した AI リンク候補を確認 — 1 件ずつ、または一括で承認または却下

Suggestions タブ

Suggestions タブには、バックグラウンドのスイープエンジンが自動生成したリンク候補が表示されます。各候補は、関連性があるとエンジンが判断した2つのメモリのペアで、コサイン類似度、BM25 キーワードの重複、エンティティの共起、時間的近接性に基づいてスコアが付けられます。

ワークフロー：

1. スイープエンジンは、設定可能な間隔（LORE_SUGGEST_INTERVAL_HOURS、デフォルトは 12）で実行されます。
2. 候補は Suggestions タブにスコア順（高い順）で表示されます。
3. ✓ をクリックするか、複数の行を選択して Accept Selected をクリックすると、2つのメモリ間に永続的なリンクが作成されます。
4. ✗ をクリックするか、Reject Selected をクリックすると候補が却下されます。却下されたペアが今後のスイープで再表示されることはありません。
5. 間隔を待たずにスイープをすぐ実行するには、Config タブの Trigger Sweep を使用します。

スイープの設定（LORE_ を接頭辞とする環境変数、または Config タブから設定）：

設定	デフォルト	説明
LORE_SUGGEST_INTERVAL_HOURS	12	スイープの実行間隔（時間）
LORE_SUGGEST_MIN_SCORE	0.55	候補を表示するための重み付きスコアの最小値
LORE_SUGGEST_MAX_CANDIDATES	500	1回のスイープでの候補の最大数
LORE_SUGGEST_TTL_DAYS	30	未確認の提案が整理されるまでの日数

---

エージェントが作り、エージェントのために

Lorekeeper は Claude Code、Hermes、および独自のエージェントチームなど、AI エージェントを_使って_開発されています。開発サイクルそのものが、Lorekeeper の機能を実際に示すデモです。

agent builds a feature → uses Lorekeeper to capture what it learned →
searches those memories next session →
builds the next feature with the context already there

これは宣伝文句ではありません。Lorekeeper のすべてのツールスキーマ、戻り値の型、ワークフローは、仕様書を読む人間ではなく、日々使っているエージェントによって形作られてきました。使いにくい点があれば変更し、検索結果にノイズが多ければ重みを調整しました。Lorekeeper が今の形になったのは、開発に携わるエージェントがそれに頼っているからです。

このリポジトリで紹介しているエージェントを活用した開発ループは、私たちが実際に取り組んでいる方法です。そして、Lorekeeper は皆さんにも同じ方法を支援できるよう設計されています。

---

開発者向け

クローンして、ソースから実行するか、開発に参加してください。

git clone https://github.com/Jessinra/Lorekeeper.git
cd Lorekeeper
bash scripts/setup.sh

# Tests
uv run pytest

# Lint
uv run ruff check src tests

# Type check
uv run mypy src

# Dashboard dev
uv sync --extra dashboard
uv run lorekeeper-dashboard

プロジェクトの構成

src/lorekeeper/
├── __main__.py          # Entrypoint — init_service() + mcp.run(stdio)
├── server.py            # FastMCP tool definitions (8 tools)
├── config.py            # Settings (pydantic-settings, LORE_ prefix)
├── models.py            # Pydantic models
├── dashboard/           # Web UI (FastAPI + uvicorn)
└── services/
    ├── orchestrator.py  # MemoryService — coordinates sub-services
    ├── memory_engine.py # Vector store abstraction
    ├── lancedb_engine.py# LanceDB backend
    ├── link_store.py    # SQLite — memories, links, suggestions
    ├── keyword_index.py # BM25 index
    ├── search.py        # Hybrid ranking
    └── ...

主な設定

すべての設定は、LORE_ を接頭辞とする環境変数、またはダッシュボードの Config タブから行えます。

変数	デフォルト	説明
LORE_DATA_DIR	~/.lorekeeper	データディレクトリ（SQLite ＋ベクトル）
LORE_NAMESPACE	shared	エージェントの名前空間 — 書き込みはスコープ化され、読み込みは shared と統合されます
LORE_SEARCH_LIMIT	5	lore_search のデフォルトの結果数
LORE_LINK_TOP_M	10	lore_recommend_links が返す候補の最大数
LORE_LINK_SCORE_THRESHOLD	0.3	リンク候補を表示するためのスコアの最小値
LORE_LINK_TEMPORAL_TAU_DAYS	30	時間的近接性のスコアリングにおける減衰の半減期（日数）

すべての設定 → src/lorekeeper/config.py と CLAUDE.md。

---

パフォーマンス

LongMemEval-S の全500問、デフォルトのハイブリッド重み（sem=0.45、kw=0.30）：

指標	値	レイテンシー
R@1	84.6%	32.9 ms/query
R@3	93.6%
R@5	96.6%
R@10	98.8%

カテゴリ別の詳細な結果 → docs/research/2026-06-11-retrieval-benchmark-results.md

---

ライセンス

Apache-2.0 — LICENSEをご覧ください。

---

エージェントが、エージェントのために構築しました。 マニフェスト · 戦略

最終確認日：2026-06-20