linksee-memory

ローカルファーストなエージェントメモリMCP。Claude Code、Cursor、ChatGPT Desktop間で共有可能な脳であり、他にはないトークン節約型のファイル差分キャッシュ機能を備えています。

npm license

機能概要

ほとんどの「エージェントメモリ」サービス（Mem0、Letta、Zep）は、事実をフラットなリストとして保存します。そのため、エージェントが「ファイルXを30回編集した」という履歴を見ても、その理由が分かりません。linksee-memoryは「なぜ（WHY）」を保持します。

これはModel Context Protocol (MCP) サーバーであり、あらゆるAIエージェントに4つの強力な機能を提供します。

	Mem0 / Letta / Zep	Claude Code 自動メモリ	linksee-memory
エージェント間共有	△ (クラウド)	❌ Claudeのみ	✅ 単一のSQLiteファイル
6層のWHY構造	❌ フラット	❌ フラットなMarkdown	✅ 目標 / コンテキスト / 感情 / 実装 / 注意点 / 学習
ファイル差分キャッシュ	❌	❌	✅ AST対応、再読み込み時に50-99%のトークン節約
アクティブな忘却	△	❌	✅ エビングハウスの忘却曲線、注意点層は保護
ローカルファースト / プライベート	❌	✅	✅

3つの柱

トークン節約: read_smartによる実現。sha256 + AST/見出し/インデント単位のチャンク分割。再読み込み時は差分のみを返します。TSファイルの編集で平均86%、変更なしの再読み込みで99%のトークンを節約。
エージェント間ポータビリティ: ~/.linksee-memory/memory.db に単一のSQLiteファイルを配置。Claude Code、Cursor、ChatGPT Desktopで同じ脳を共有します。
WHY重視の構造化メモリ: 6つの明示的な層（目標 / コンテキスト / 感情 / 実装 / 注意点 / 学習）を使用。「目標なしのフラットな事実メモリは役に立たない」という問題を解決します。

インストール

npm install -g linksee-memory
linksee-memory-import --help   # bundled importer for Claude Code session history

または npx を一時的に使用する場合:

npx linksee-memory             # starts the MCP server on stdio

デフォルトのデータベースは ~/.linksee-memory/memory.db に作成されます。環境変数 LINKSEE_MEMORY_DIR で変更可能です。

Claude Codeへの登録

claude mcp add -s user linksee -- npx -y linksee-memory

Claude Codeを再起動してください。mcp__linksee__remember、mcp__linksee__recall、mcp__linksee__recall_file、mcp__linksee__read_smart、mcp__linksee__forget、mcp__linksee__consolidate というツールが表示されます。

オプション: 全セッションの自動キャプチャ (Stopフック)

~/.claude/settings.json に以下を追加すると、すべてのClaude Codeセッションがローカルの脳に自動的に記録されます:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "npx -y linksee-memory-sync" }
        ]
      }
    ]
  }
}

各ターンの終了時に約100msかかります。失敗してもサイレントに処理されます（Claude Codeがブロックされることはありません）。ログは ~/.linksee-memory/hook.log に出力されます。

ツール

ツール	目的
`remember`	エンティティに対して6つの層のいずれかにメモリを保存
`recall`	FTS5 + ヒートスコア + モメンタム複合ランキング、日本語/英語のトライグラム検索
`recall_file`	全セッションを通じたファイルの完全な編集履歴を、編集ごとのユーザー意図コンテキスト付きで取得
`read_smart`	差分のみのファイル読み込み。初回は全内容、変更なしの再読み込み時は約50トークン、実際の編集時は変更されたチャンクのみを返す
`forget`	明示的な削除、または忘却リスク（重要度 × ヒート × 経過時間）に基づく自動削除
`consolidate`	スリープモード圧縮：重要度の低い古いメモリをクラスタリングし、保護された学習層の要約に変換

6つのメモリ層

各エンティティ（人 / 企業 / プロジェクト / ファイル / コンセプト）は、6つの層にわたってメモリを持つことができます。各層はカテゴリではなく意味をエンコードします:

{
  "goal":    { "primary": "...", "sub_tasks": [], "deadline": "..." },
  "context": { "why_now": "...", "triggering_event": "...", "when": "..." },
  "emotion": { "temperature": "hot|warm|cold", "user_tone": "..." },
  "implementation": {
    "success": [{ "what": "...", "evidence": "..." }],
    "failure": [{ "what": "...", "why_failed": "..." }]
  },
  "caveat":  [{ "rule": "...", "reason": "...", "from_incident": "..." }],
  "learning":[{ "at": "...", "learned": "...", "prior_belief": "..." }]
}

注意点（caveat）メモリは忘却から自動的に保護されます（痛みを伴う教訓は決して失われません）。
目標（goal）メモリは、目標がアクティブな間は減衰を回避します。

アーキテクチャ

単一のSQLiteファイル（better-sqlite3 + 日本語/英語用FTS5トライグラムトークナイザー）に5つの層が含まれています:

第1層 — entities（事実：人 / 企業 / プロジェクト / コンセプト / ファイル）
第2層 — edges（関連性、グラフの隣接関係）
第3層 — memories（エンティティごとの6層構造の意味）
第4層 — events（ヒート / モメンタム計算用の時系列ログ）
第5層 — file_snapshots + session_file_edits（差分キャッシュ + 会話↔ファイルのリンク）

会話とファイルのリンクが鍵となります。Stopフックによってキャプチャされたすべてのファイル編集は、その編集を促したユーザーメッセージと共に保存されます。そのため、recall_file("server.ts") を実行すると、「このファイルは3日間で30回編集され、各変更の動機となった実際のユーザー指示はこれです」といった情報を取得できます。

設計の理由

ローカルファースト: 会話履歴はプライベートです。マシンからデータが外部に出ることはありません。
単一ファイル: memory.db はポータブルな成果物です。バックアップはファイルのコピーだけで完了します。
MCP stdio: MCPに対応したすべてのエージェントで動作し、ホストごとのプラグインは不要です。
実績のあるスキーマの再利用: heat_score / momentum_score は、本番環境のセールスインテリジェンスコードベースから移植されました。ルールベースであり、ホットパスにLLM依存関係はありません。

ロードマップ

✅ 6つの主要MCPツール（remember / recall / recall_file / forget / consolidate / read_smart）
✅ Claude Code用Stopフック自動キャプチャ
✅ 日本語/英語トライグラムFTS5
🚧 Readを自動インターセプトする PreToolUse フック（設定不要のトークン節約）
🚧 Cursor + ChatGPT Desktopアダプター
🔮 ベクトル検索（埋め込みバックエンド選択後、sqlite-vecを使用）
🔮 オプションの匿名テレメトリ → MCP品質のインテリジェンス層

Claude Code自動メモリとの比較

Claude Codeには ~/.claude/projects/<path>/memory/*.md に組み込みのメモリ機能がありますが、これはユーザー設定用のフラットなMarkdownノートです。linksee-memoryはこれを補完します:

自動メモリ = 「Xを好むことを覚えておいて」というスクラップブック
linksee-memory = ファイル差分キャッシュと編集ごとの「WHY」を備えた構造化されたエージェント間共有脳

両方を使用してください。

テレメトリ（オプトイン、デフォルトでオフ）

linksee-memoryには、どのMCPサーバーやワークフローが実際に現場で機能しているかを理解するためのオプトイン匿名テレメトリが同梱されています。明示的に有効にしない限り、何も送信されません。 会話内容、ファイル内容、エンティティ名、プロジェクトパスなどは一切送信されません。

有効化

export LINKSEE_TELEMETRY=basic     # opt in
export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)

送信される内容（レベル1契約）

各Claude Codeセッション終了後、Stopフックが https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee に以下のフィールドのみを含むPOSTを1回送信します:

フィールド	例	内容
`anon_id`	`d7924ced-3879-…`	初回オプトイン時にローカルで生成されるランダムUUID。`~/.linksee-memory/telemetry-id` に保存。ファイルを削除するとリセットされます。
`linksee_version`	`0.0.3`	パッケージバージョン
`session_turn_count`	`120`	セッションのターン数
`session_duration_sec`	`3600`	セッションの継続時間
`file_ops_edit/write/read`	`12, 2, 40`	操作回数のみ
`mcp_servers`	`["kansei-link","freee","slack"]`	設定されているMCPサーバー名（`~/.claude.json`より）。名前のみで、コマンドパスは含まれません。
`file_extensions`	`{".ts":60,".md":30}`	触れたファイル拡張子の割合
`read_smart_`, `recall_`	カウント	ツール使用回数

送信されないもの:

❌ 会話メッセージ（ユーザーまたはアシスタント）
❌ ファイル内容
❌ エンティティ名、プロジェクト名、ファイルパス、URL
❌ メモリ層のテキスト（目標 / コンテキスト / 感情 / 実装 / 注意点 / 学習）
❌ 認証トークン、APIキー、シークレット
❌ IPアドレス（不正利用検知のための片方向ハッシュのみ）

なぜ収集するのか

集計されたMCP使用データは、KanseiLink プロジェクトが、どのエージェント統合が実際の開発者にとって有効かをランク付けするのに役立ちます。貢献いただける場合、LINKSEE_TELEMETRY=basic を設定するだけで、MCPエコシステム全体の改善に繋がります。

完全なペイロードスキーマと検証ロジックはオープンソースです。マシンから何が送信されるか正確に確認したい場合は src/lib/telemetry.ts をお読みください。

ライセンス

MIT — Synapse Arrows PTE. LTD.

Linksee Memory