research: MemOS / Letta Context Repositories — Session Memory Phase 2 の設計参考

[clonable-eden]

Summary

cekernel の Session Memory Phase 2 (#101) の設計にあたり、MemOS と Letta Context Repositories の知見を整理する。

#86 のリサーチアップデートで「MemOS や Letta の Context Repositories が参考になる」と指摘した点を深掘りした結果。

背景

ADR-0002 Phase 2 は SQLite session DB を想定しているが、Letta Context Repositories の事例は「ファイル + git で驚くほど遠くまで行ける」ことを示している。Phase 2 の設計判断に向けて、3つのアプローチを比較する。

3つのアプローチ比較

軸	ADR-0002 Phase 2 (SQLite)	MemOS	Letta MemFS
ストレージ	SQLite 1ファイル	Neo4j + Qdrant + Redis + PostgreSQL	Git リポジトリ (markdown files)
メモリの単位	テーブル行 (key-value)	MemCube (メタデータヘッダ + ペイロード)	Markdown ファイル (YAML frontmatter)
ライフサイクル	なし (暗黙的に session 寿命)	5状態 (Generated→Activated→Merged→Archived→Expired)	なし (git history が暗黙的に管理)
共有モデル	共有DB に直接 read/write	Pub/Sub (MemStore)	共有ブロック or git merge
並行制御	SQLite WAL (concurrent read)	未定義 (NLI で事後重複排除)	last-write-wins or git conflict resolution
UNIX哲学	○ (sqlite3 CLI, jq, 既存ツール)	× (専用APIサーバー群)	◎ (ファイル + git + bash)
運用コスト	ゼロ (ファイル1つ)	高 (Docker Compose, 4サービス)	低 (git + filesystem)

MemOS から得られる示唆

メモリメタデータの概念

MemOS の MemCube は各メモリに構造化メタデータ (origin, semantic_type, access_frequency, priority) を付与する。ADR-0002 の worker_notes は key + value のフラットな構造で、Worker B が Worker A の発見を見つけられるかは key の命名規約に依存する。

最低限のメタデータ列 (kind: finding / warning / dependency) を追加すると発見性が向上する可能性がある。

ただし MemOS のフル仕様 (TTL, decay, ACL, priority) は cekernel の規模では over-engineering。MemOS 自体も論文上は精緻だが実装では多くが未指定。

参考文献

• 論文: https://arxiv.org/abs/2507.03724
• GitHub: https://github.com/MemTensor/MemOS
• v2.0 "Stardust" (2025年12月): Redis Streams scheduler, KB features, MCP 統合

Letta Context Repositories から得られる示唆

ファイル + git = メモリ管理

Letta MemFS のアーキテクチャは cekernel と驚くほど似ている:

Letta MemFS	cekernel (現状)
メモリ = markdown ファイル	タスク/チェックポイント = markdown/JSON ファイル
git commit で変更追跡	git worktree で変更分離
git merge でマルチエージェント統合	FIFO + state file で完了通知
system/ フォルダ = 常時ロード	.cekernel-task.md = spawn 時に注入

SQLite ではなくファイル + git を選んだ理由

1. Transparency: git log でメモリの変更履歴が見える
2. Composability: bash、jq、grep で操作できる
3. Conflict resolution: git merge という枯れたメカニズムを再利用
4. Rollback: git revert でメモリ状態を巻き戻せる

これは ADR-0002 が掲げる UNIX 哲学 (Rule of Transparency, Rule of Composition) と完全に一致する。

参考文献

• Context Repositories blog: https://www.letta.com/blog/context-repositories
• Memory Blocks blog: https://www.letta.com/blog/memory-blocks
• Letta Code Memory docs: https://docs.letta.com/letta-code/memory/

Phase 2 の設計パス候補

パス A: 現在の ADR-0002 路線 (SQLite)

/tmp/cekernel-ipc/{SESSION_ID}/memory.db
  ├── issue_cache    → spawn 時キャッシュ
  └── worker_notes   → Worker 間知識共有

• 長所: sqlite3 CLI で query 可能、WAL で concurrent read 安全、既にADR設計済み
• 短所: session 寿命で消える。cross-session 知識の蓄積なし

パス B: Letta 式ファイルベース

/tmp/cekernel-ipc/{SESSION_ID}/memory/
  ├── issues/4.json           → issue cache
  ├── notes/4-api-retry.md    → Worker A の発見
  └── notes/5-auth-fix.md     → Worker B の発見

• 長所: 現行の file-based パターンと一貫性がある。UNIX 哲学に最も忠実
• 短所: concurrent write の安全性は自前で保証が必要 (ただし Worker ごとに issue が異なるため実質衝突しない)

パス C: ハイブリッド

issue_cache     → 現状の .cekernel-task.md をそのまま維持 (file)
worker_notes    → SQLite (structured query が必要な場合のみ)

判断基準

1. Worker 間知識共有の具体的ニーズが発生したか? → まだ No なら Rule of Optimization に従い保留
2. 発生した場合、知識の検索性が必要か? → Yes なら SQLite (パス A/C)。No なら file (パス B) で十分
3. cross-session の知識蓄積が必要か? → Yes なら IPC dir 外への永続化が必要 (ADR-0002 の scope 外)

結論

Letta の事例が示す最大の教訓は「ファイル + git で驚くほど遠くまで行ける」こと。cekernel は既にそのパス上にいるので、SQLite への移行は「ファイルベースでは解決できない具体的な問題」が出てからでも遅くない。

Related: #101, #86

[clonable-eden]

subagent memory field 一次確認結果 (2026-06-07)

#530 で公式 docs を確認した結果、subagent frontmatter の memory field は実在することを確定しました。先のコメントを取り下げて、確定情報として記録します。

仕様（一次ソース確認済み）

• field 名: memory
• 値: user | project | local
• 保存先:
  • user → ~/.claude/agent-memory/<name-of-agent>/
  • project → .claude/agent-memory/<name-of-agent>/
  • local → .claude/agent-memory-local/<name-of-agent>/
• 挙動: subagent の system prompt に memory dir の read/write 指示が自動注入される。さらに MEMORY.md の先頭 200 行（or 25KB）が context に取り込まれる。Read / Write / Edit tool が自動で enable される。

URL: https://code.claude.com/docs/en/subagents.md#enable-persistent-memory

Phase 2 比較表に「パス D」を追加

軸	パス A (SQLite)	パス B (Letta MemFS)	パス C (Hybrid)	パス D: native subagent memory
ストレージ	memory.db (sqlite)	file + git	task=file, notes=sqlite	.claude/agent-memory/<agent>/ (markdown)
メモリ単位	row	markdown ファイル	mixed	markdown ファイル + MEMORY.md index
ライフサイクル	session 寿命	git history	mixed	local (gitignored) / project (commit) / user (machine 共有)
Worker 間共有	DB read/write	git merge	mixed	scope による（project なら共有、local なら隔離）
UNIX 哲学	○	◎	○	◎（既存 file + git 哲学とそのまま整合）
運用コスト	低	低	中	極低（Claude Code が自動管理）
cross-session	× (IPC 寿命)	○	×	○
採用コスト	ADR-0002 を実装	ADR-0002 を再設計	同左	frontmatter に 1 行追加

評価

パス D が破壊力高い。.claude/agent-memory/<agent>/MEMORY.md を Claude Code が自動でロード／編集してくれるため、cekernel 側に追加実装は不要。Letta の Context Repositories と概念がほぼ同じで、しかも公式機能として組み込まれている。

ただし注意点：

• パス D は subagent 用 であって、cekernel の Worker は subagent ではなく独立 OS プロセス。そのまま使うには Worker を subagent 化するか、Reviewer のみに適用する形になる。
• local / project scope は git/repo 単位なので、cross-repo 利用時の挙動を確認する必要あり。

アクション

• Reviewer agent の frontmatter に memory: project を試験追加し、過去の review パターン蓄積を試す（小さな PoC）
• Worker は現状の .cekernel-task.md 維持。subagent 化と memory 採用は ADR-0012 再評価 issue（research: Claude Code 新機能の一次確認（claude agents / --bare / subagent memory / isolation） #530 結果から派生予定）と統合検討
• 本 issue (research: MemOS / Letta Context Repositories — Session Memory Phase 2 の設計参考 #199) は 「パス D を第一選択肢として検討」 に方針更新

関連

• research: Claude Code 新機能の一次確認（claude agents / --bare / subagent memory / isolation） #530 で一次確認済み（クローズ予定）
• ADR-0012 再評価（research: Claude Code 新機能の一次確認（claude agents / --bare / subagent memory / isolation） #530 のフォローアップ）