neural-memory

NeuralMemory — AI エージェント向け連想記憶

キーワード検索やベクトル検索の代わりに、活性化の伝播を利用する、生物学に着想を得た記憶システムです。記憶は、20 種類の型付きシナプスでニューロンがつながるニューラルグラフを形成します。頻繁に同時にアクセスされる記憶は、そのつながりが強化されます（ヘッブ学習）。古くなった記憶は自然に減衰します。矛盾は自動検出されます。

ベクトル検索だけではだめなのですか？ ベクトル検索は、クエリに似たドキュメントを見つけます。NeuralMemory は、キーワードや埋め込みに重なりがなくても、グラフをたどって概念的に関連する記憶を見つけます。「認証についてどのような決定をしましたか？」という質問では、時間・エンティティ・概念のニューロンが同時に活性化し、その交差部分が見つかります。

セットアップ

1. NeuralMemory をインストールする

pip install neural-memory

初回使用時に、脳と設定が ~/.neuralmemory/ に自動作成されます。

2. OpenClaw プラグインをインストールする（推奨）

プラグインは専用のメモリスロットを占有します。エージェントの実行前にコンテキストを自動注入し、実行後に記憶を自動取得します。

# Install from npm
npm install -g neuralmemory

~/.openclaw/openclaw.json に追加します。

{
  "plugins": {
    "load": {
      "paths": ["<path-to-installed-plugin>"]
    },
    "entries": {
      "neuralmemory": {
        "enabled": true,
        "config": {
          "pythonPath": "python",
          "brain": "default",
          "autoContext": true,
          "autoCapture": true
        }
      }
    },
    "slots": {
      "memory": "neuralmemory"
    }
  }
}

プラグインの機能：

• 6 つのツールを自動登録します（nmem_remember、nmem_recall、nmem_context、nmem_todo、nmem_stats、nmem_health）
• before_agent_start フック：ツールの説明と関連する記憶をコンテキストとして注入します（/new の後も保持されます）
• agent_end フック：会話から事実、決定事項、TODO を自動抽出します
• 設定可能：contextDepth（0～3）、maxContextTokens（100～10000）

インストール後、プラグインをビルドします。

cd <path-to-installed-plugin>
npm run build

これにより、TypeScript が dist/ 内の JavaScript にコンパイルされます。プラグインのエントリーポイントは dist/index.js です。

Windows でのインストール

Windows では、openclaw.json のパスにスラッシュまたはエスケープしたバックスラッシュを使用します。

{
  "plugins": {
    "load": {
      "paths": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/neuralmemory"]
    }
  }
}

インストール先のパスを確認するには、次のコマンドを実行します。

npm list -g neuralmemory --parseable

openclaw plugins list にプラグインが表示されない場合：

1. openclaw.json のパスが、パッケージのルート（package.json がある場所）を指していることを確認します
2. npm run build を実行したことを確認します（コンパイル済みの .js ファイルを含む dist/ フォルダーが必要です）
3. プラグイン設定では、python3 の代わりに python を使用します（Windows のデフォルト）

代替方法：MCP の設定（手動）

プラグインではなく MCP を使用する場合は、~/.openclaw/mcp.json に追加します。

{
  "mcpServers": {
    "neural-memory": {
      "command": "python",
      "args": ["-m", "neural_memory.mcp"],
      "env": {
        "NEURALMEMORY_BRAIN": "default"
      }
    }
  }
}

Windows では "python3" ではなく "python" を使用します。これにより、63 個すべての MCP ツールを利用できますが、コンテキストの自動注入／自動取得フックは利用できません。

3. 確認する

nmem stats

脳の統計情報（ニューロン、シナプス、ファイバー）が表示されます。

トラブルシューティング

症状	原因	対処方法
openclaw plugins list にプラグインが表示されない	プラグインのパスが間違っているか、ビルドされていない	npm run build を実行し、openclaw.json のパスを確認します
エージェントがターミナルで nmem remember を実行する	エージェントが CLI とツールを混同している	プラグインが systemPrompt を通じてツールの説明を自動注入するようになりました
/new の後、エージェントがツールを忘れる	新しいセッションにツールの説明がない	プラグインはすべての before_agent_start で systemPrompt を注入するようになりました
python3 not found（Windows）	Windows では python3 ではなく python を使用する	プラグイン設定で pythonPath: "python" を設定します
タイムアウトエラー	マシンの動作が遅いか、脳が大きい	プラグイン設定の timeout を増やします（最大 120000ms）

ツールリファレンス

コアメモリツール

ツール	目的	使用する場面
nmem_remember	記憶を保存する	決定事項、エラー、事実、洞察、ユーザーの好みの後
nmem_recall	記憶を検索する	タスクの前、ユーザーが過去のコンテキストに言及したとき、「覚えていますか……」と尋ねられたとき
nmem_context	最近の記憶を取得する	セッション開始時に、新しいコンテキストを注入する
nmem_todo	30 日で期限切れになる簡易 TODO	タスクの追跡

インテリジェンスツール

ツール	目的	使用するタイミング
nmem_auto	テキストから記憶を自動抽出します	重要な会話の後。決定事項、エラー、TODO を自動的に記録します
nmem_recall (depth=3)	深い連想による想起	分野をまたぐつながりが必要な複雑な質問
nmem_habits	ワークフローパターンの提案	ユーザーが似たような一連の操作を繰り返すとき

管理ツール

ツール	目的	使用するタイミング
nmem_health	脳の健全性の診断	定期点検、脳を共有する前
nmem_stats	脳の統計情報	記憶の件数をすばやく確認するとき
nmem_version	脳のスナップショットとロールバック	リスクのある操作の前、バージョンのチェックポイント作成時
nmem_transplant	脳間で記憶を転送します	プロジェクト間でナレッジを共有するとき

ワークフロー

セッション開始時

1. nmem_context を呼び出して、最近の記憶を意識に取り込みます
2. ユーザーが特定のトピックに言及した場合は、そのトピックを指定して nmem_recall を呼び出します

会話中

3. 決定事項が決まったとき：type="decision" を指定して nmem_remember を呼び出します
4. エラーが発生したとき：type="error" を指定して nmem_remember を呼び出します
5. ユーザーが好みを述べたとき：type="preference" を指定して nmem_remember を呼び出します
6. 過去の出来事について尋ねられたとき：適切な深度で nmem_recall を呼び出します

セッション終了時

7. 重要な会話の部分を対象に、action="process" を指定して nmem_auto を呼び出します
8. これにより、事実、決定事項、エラー、TODO が自動的に抽出されます

例

決定事項を記憶する

nmem_remember(
  content="Use PostgreSQL for production, SQLite for development",
  type="decision",
  tags=["database", "infrastructure"],
  priority=8
)

活性拡散による想起

nmem_recall(
  query="database configuration for production",
  depth=1,
  max_tokens=500
)

キーワードの照合ではなく、グラフ探索で見つかった記憶を返します。関連する記憶（例：「デプロイでは Docker を使い、pg_dump でバックアップする」）は、共通のキーワードがなくても浮かび上がります。

因果関係の連鎖をたどる

nmem_recall(
  query="why did the deployment fail last week?",
  depth=2
)

CAUSED_BY と LEADS_TO のシナプスをたどり、原因と結果の連鎖を追跡します。

会話から自動的に取り込む

nmem_auto(
  action="process",
  text="We decided to switch from REST to GraphQL because the frontend needs flexible queries. The migration will take 2 sprints. TODO: update API docs."
)

決定事項 1 件、事実 1 件、TODO 1 件を自動的に抽出します。

主な機能

• LLM 依存ゼロ — 正規表現、グラフ探索、ヘブ学習による純粋なアルゴリズム処理です
• 活性拡散 — キーワード検索やベクトル検索ではなく、ニューラルグラフを通じた連想的な想起です
• 20 種類のシナプス — 時間的（BEFORE/AFTER）、因果的（CAUSED_BY/LEADS_TO）、意味的（IS_A/HAS_PROPERTY）、感情的（FELT/EVOKES）、競合（CONTRADICTS）
• 記憶のライフサイクル — 短期 → 作業 → エピソード → 意味記憶。エビングハウスの忘却曲線による減衰を伴います
• 矛盾の検出 — 矛盾する記憶を自動検出し、古くなった記憶の優先度を下げます
• ヘブ学習 — 「共に発火するニューロンは共に結びつく」——使うほど記憶が向上します
• 時間的推論 — 因果関係の連鎖のたどり、イベントの順序、時間範囲によるクエリに対応します
• 脳のバージョン管理 — 脳の状態のスナップショット作成、ロールバック、差分確認
• 脳の移植 — フィルタリングした知識を脳間で転送します
• ベトナム語＋英語 — 抽出と感情分析における完全なバイリンガル対応

深度レベル

深度	名前	速度	用途
0	即時	<10ms	簡単な事実、最近のコンテキスト
1	コンテキスト	~50ms	標準的な想起（デフォルト）
2	習慣	~200ms	パターン照合、ワークフローの提案
3	深層	~500ms	分野をまたぐ関連付け、因果関係の連鎖

注意事項

• 記憶は ~/.neuralmemory/brains/<brain>.db の SQLite にローカル保存されます
• （オプションの埋め込みプロバイダーが設定されている場合を除き）外部サービスにデータは送信されません
• 脳の分離：各脳は独立しており、相互に混ざることはありません
• nmem_remember は参照追跡用に fiber_id を返します
• 優先度の範囲：0（些細）～10（重大）、デフォルトは 5
• 記憶の種類：fact、decision、preference、todo、insight、context、instruction、error、workflow、reference