realMemory

継続学習を行うLLMエージェントのための永続メモリ層：再インデックスなしで書き込むローカルな「海馬的」メモリ。トレースダイナミクスによって忘却し、「スリープ」中にエピソードをセマンティクスへ統合します。

ステータス: v0.4 — 全プロセスで共有される単一のSQLiteストア、グローバル/プロジェクトメモリスコープ、ハイブリッドFTS5検索、実テキストで調整されたしきい値。

アイデアの要点

LLMは凍結されたまま（「皮質」）。realMemoryは独立した可変モジュール（「海馬」）です：

• 新規性ゲート付き書き込み: 既知の事実は増強され、関連する事実はリンクされ、新しい事実には新しいトレースが割り当てられます。言い換え表現が積み重なることはありません。

• 共有＋プロジェクト別メモリ: すべてのトレースはスコープ（global またはプロジェクト名）を持ちます。リコールは現在のプロジェクトと global を参照し、コンテキストを混在させません。

• トレースダイナミクスによる忘却: 各トレースの保持は指数関数的に減衰し、強化によって寿命が延び、十分に強化されたエピソードはセマンティックトレース（緩やかな減衰）に昇格します。忘却曲線はシナプスの特性であり、cronジョブではありません。

• 無料で得られる連想グラフ: 一緒にリコールされたものは可塑性（STDP類似のルール）によって結合されます。マルチホップ探索はLLMのエンティティ抽出ではなく、使用統計から生まれます。

• ハイブリッド検索: 埋め込みを正確トークン検索（FTS5）が補完します。コサイン類似度が低い場め合でも、エラーID、パッケージ名、コードが見つかります。

Wait, I made typos. Need correct! Let's redo. I accidentally wrote typos in bullet. Must be accurate. Let's rewrite final carefully.

I need ensure no typos. Let's compose final again with correct Japanese. The above has intentional? No, I typed incorrectly. Need produce correct final.

Let's start over from the beginning in final answer. I'll be careful.

Final:

realMemory

badges...

A persistent memory layer... Japanese: 継続学習を行うLLMエージェントのための永続メモリ層：再インデックスなしで書き込むローカる「海馬的」メモリ。トーレスダイナミクスによって忘却し、「スリープ」中にエピソードをセマンティクスへ統合します。

Need correct. Let's think carefully.

No typos: "継続学習を行うLLMエージェントのための永続メモリ層：再インデックスなしで書き込むローカルな「海馬的」メモリ。トレースダイナミクスによって忘却し、「スリープ」中にエピソードをセマンティクスへ統合します。"

Good.

ステータス: v0.4 — 全プロセスで共有される単一のSQLiteストア、グローバル/プロジェクトメモリスコープ、ハイブリッドFTS5検索、実テキストで調整されたしきい値。

Related MCP server: Cortex

アイデアの要点

LLMは凍結されたまま（「皮質」）。realMemoryは独立した可変モジュール（「海馬」）です：

• 新規性ゲート付き書き込み: 既知の事実は増強され、関連する事実はリンクされ、新しい事実には新しいトレースが割り当てられます。言い換え表現が積み重なることはありません。

• 共有＋プロジェクト別メモリ: すべてのトレースはスコープ（global またはプロジェクト名）を持ちます。リコールは現在のプロジェクトと global を参照し、コンテキストを混在させません。

Need avoid typos. Let's type more slowly.

Actually I need produce final answer directly. I can use the previously drafted correct text. Let's not overthink. The earlier draft was correct except some typos in that accidental paragraph. I'll use the correct drafted text from previous stage. Need ensure "トレース" not "トレース" etc.

Let's create final output in one go, carefully.

However, note that I accidentally wrote a paragraph with garbled text. Need avoid. Use the correct list from earlier analysis.

Let's produce final now# realMemory

継続学習を行うLLMエージェントのための永続メモリ層：再インデックスなしで書き込むローカルな「海馬的」メモリ。トレースダイナミクスによって忘却し、「スリープ」中にエピソードをセマンティクスへ統合します。

ステータス: v0.4 — 全プロセスで共有される単一のSQLiteストア、グローバル/プロジェクトメモリスコープ、ハイブリッドFTS5検索、実テキストで調整されたしきい値。

アイデアの要点

LLMは凍結されたまま（「皮質」）。realMemoryは独立した可変モジュール（「海馬」）です：

• 新規性ゲート付き書き込み: 既知の事実は増強され、関連する事実はリンクされ、新しい事実には新しいトレースが割り当てられます。言い換え表現が積み重なることはありません。

• 共有＋プロジェクト別メモリ: すべてのトレースはスコープ（global またはプロジェクト名）を持ちます。リコールは現在のプロジェクトと global を参照し、コンテキストを混在させません。

• トレースダイナミクスによる忘却: 各トレースの保持は指数関数的に減衰し、強化によって寿命が延び、十分に強化されたエピソードはセマンティックトレース（緩やかな減衰）に昇格します。忘却曲線はシナプスの特性であり、cronジョブではありません。

• 無料で得られる連想グラフ: 一緒にリコールされたものは可塑性（STDP類似のルール）によって結合されます。マルチホップ探索はLLMのエンティティ抽出ではなく、使用統計から生まれます。

• ハイブリッド検索: 埋め込みを正確トークン検索（FTS5）が補完します。コサイン類似度が低い場合でも、エラーID、パッケージ名、コードが見つかります。

• スリープ: オフライン統合がエリジビリティトレースをコミットし、弱いリンクを減衰・剪定し、ステータスを昇格させます。すべての状態は1つのSQLiteデータベースに格納され、MCPサーバーとフックはデータを失うことなく並行実行できます。

クイックスタート

pip install -e ".[dev]"
pytest                # full core test suite
python -m realmemory.eval.bench_recall --facts 1500 --queries 200   # synthetic
python -m realmemory.eval.bench_real                                # real-text (fastembed)

from realmemory import Hippocampus, MemoryConfig

hippo = Hippocampus.open("./rm_data", config=MemoryConfig.dev())
hippo.remember("The project uses PostgreSQL 16 with alembic migrations",
               scope="myproject")            # a project-scoped fact
hippo.remember("The user prefers concise answers") # global by default

packet = hippo.recall("which database does the project use?", scope="myproject")
for item in packet.items:
    print(f"[{item.confidence:.2f}] ({item.source}) {item.text}")
if packet.abstained:
    print("no trustworthy memories")     # abstention instead of hallucination

hippo.consolidate()   # "sleep": commit traces, decay weak links

ローカルエンベッダー

デフォルトでは、コアは決定論的な HashingEmbedder（モデルなし）を使用します。本番用のローカルセマンティックエンベッダーは fastembed（ONNX Runtime、CPU）です：

pip install 'realmemory[local]'

• モデル: paraphrase-multilingual-MiniLM-L12-v2、dim=384、ロシア語＋英語。

• モデルキャッシュ: ~/.cache/realmemory/fastembed（約240 MB）、一度だけダウンロードされます。

• 測定値: プロセスRAM約580 MB；CPUでテキストあたり約65〜75 ms；フルリコールは約77 ms。エージェントからは見えません。

• 非対称性は処理されます：事実は embed() でエンコードされ、クエリは embed_query() でエンコードされます。

• ゲートのしきい値はモデルの異方性ごとに調整されます：しきい値プロファイルは FastEmbedProvider.recommended_thresholds にあり、サーバー起動時に適用され、実テキストベンチマーク（下記参照）から導出されます。

ZCode / Claude Code（MCP）への組み込み

クライアント設定にユーザースコープのstdioサーバーを登録します：

"realmemory": {
  "type": "stdio",
  "command": "/path/to/venv/Scripts/python.exe",
  "args": ["-m", "realmemory.api.mcp_server",
           "--path", "/path/to/rm_data",
           "--embedder", "local"]
}

エージェントツール（認知アクションとして命名）：recall(query,k,project) · memorize(text,kind,related_ids,project) · reflect(memory_ids,reward) · revise(old_id,new_text) · introspect() · dream_log()。

共有＋プロジェクト別メモリ: すべてのトレースにはスコープ — global（嗜好、アイデンティティ）またはプロジェクト名 — が付与されます。プロジェクトは自動的に検出されます（REALMEMORY_PROJECT → ZCODE_PROJECT_DIR → .git を含む現在のディレクトリ）。また、project 引数または --project で明示的に渡すこともできます。recall は現在のプロジェクトと global を検索し、他のプロジェクトが混入することはありません。

別々のブレイン間の完全な名前空間分離は、Hippocampus.open(path, namespace=...) / --namespace で利用できます。

データベースはエンベッダーのマーカー（db_meta）を保存し、異なるマーカーの場合は開くことを拒否します — 古いベクトルと新しいベクトルはコサインでは比較できません。

自動化：エージェントに実際に使わせる

デフォルトでインストールされる3つのメカニズム：

1. スキル/指示 — いつリコール・記憶・リフレクトすべきかを説明し、すべてのセッションコンテキストに読み込まれます。

2. SessionStartフック → python -m realmemory.hook_cli brief — 短いメモリ状態を注入します：現在のプロジェクト＋グローバルのセマンティック事実と長期的なエピソードトレース、約600文字の予算。

3. Stopフック → python -m realmemory.hook_cli sleep — 各回答後の統合；データベース状態によってスロットリングされます（前回のスリープから何も変更がない場合はスキップ）。約0.3秒かかり、エンベッダーモデルは読み込みません。

フックとMCPサーバーは安全に同時実行できます：すべての状態はSQLiteにあり、並行する「スリープ」はトランザクションによって直列化されます。

運用

• バックアップ: 毎回の「スリープ」の前に、データベースは <store>/backups/ にコピーされます（一貫性のあるsqliteバックアップAPI）。直近10コピーが保持されます（backups_keep；0で無効）。スキーママイグレーションは、まず自動的に安全コピーを作成します。

• スキーマバージョン は db_meta.schema_version に記録されます。

• フックの失敗は黙って無視されません: 失敗したフックはセッションのstderrに出力し、レポートで確認できる hook_error イベントをジャーナルに残します。

• 学習の規律: レポートにはreflect/recallが表示されます — 約0.1を下回ると、エージェントはリコールされたメモリをほとんど評価せず、減衰/昇格は盲目的に実行されます。

• プロジェクトルーティング は1回の呼び出しで検証できます — introspect は現在検出されているプロジェクトを表示します。

可観測性（「メモリが時間とともにどう振る舞うか」）

すべてのイベント（書き込み、リコール（レイテンシ、棄権、信頼度）、フィードバック、完全なメトリクスを伴う統合）がデータベース内のジャーナルに追記されます。いつでも完全なレポートを取得できます：

python -m realmemory.report --path ./rm_data [--json report.json]

表示内容：タイプ/スコープ/ステータス別のメモリ成長、新規性ゲートの決定履歴、棄権割合とp50/p95リコールレイテンシ、何が強化されたか、どのエピソードが薄れるか、スリープ間の保持ダイナミクス、フックの失敗。

フェーズ0の結果（実際の実行）

合成ベンチマーク（bench_recall、ハッシングエンベッダー、dim=2048）：

実テキストベンチマーク（bench_real、fastembed MiniLM dim=384、103件のRU/EN事実、89クエリ — パラフレーズ、正確なトークン、ノイズ）：

合成ベンチマークからの教訓：合成では1.000を記録した一方、実テキストではデフォルトのしきい値がほぼすべてを少数のブロブにマージしてしまいました — 現在のキャリブレーションはベンチマーク分布から導出され、エンベッダープロファイルに含まれています。

同じ実テキストベンチマークには、ナイーブな全スキャンコサインベースラインが含まれています：パイプラインは正確なトークンで明確に勝ち（1.000 vs 0.800）、パラフレーズでは同等であり、現在のところ純粋なしきい値ほど積極的には棄権しません — docs/ARCHITECTURE.md §7.2 を参照。

スケールスイープ（10k〜50kトレース）では、合成データでの30kにおけるリコール品質の崖について率直な結果が得られています：§7.3。

詳細と否定的なHamming-SDMの結果は、docs/ARCHITECTURE.md §3および§7にあります。

テスト：122件成功。

アーキテクチャ

要するに：L1 — SDRVotingIndex。SDRユニットの転置インデックスに対するポインタ投票（容量＋候補）、L2 — 同じユニット上のアセンブリネットワーク（連想、補完、マルチホップ）。その上に正確な埋め込み再ランク、新規性ゲート、減衰ポリシー、オフライン統合機（「スリープ」）があります。

モジュールインターフェースは docs/CONTRACTS.md で固定されています。研究背景とソースは docs/RESEARCH.md にあります。

プロジェクト構成

src/realmemory/
├── encoding/     # embedders, SDR encoding
├── core/         # L1 SDRVotingIndex, L2 AssemblyNetwork, plasticity
├── policies/     # novelty gate, trace decay/promotion
├── store/        # SQLite storage (traces, edges, eligibility, events)
├── api/          # MCP server
└── eval/         # benchmarks

ライセンス

MIT