Agentmem

agentmem

Claude Code、Cursor、Codex 向けの共有メモリです。何が今も有効なのかを把握できます。セッションを保存し、古くなったルールや矛盾するルールを検出して、エージェントが過去の間違いを繰り返すのを防ぎます。

問題

AI コーディングアシスタントは、セッションが変わるとすべてを忘れてしまいます。過去の間違いを繰り返し、現在のルールと古くなったルールを見分けられません。コンテキストが圧縮されると、復旧は困難です。

ほとんどのメモリツールが解決するのは保存です。agentmem が解決するのは信頼性です。

はじめに（Claude Code / Cursor / Codex）

pip install quilmem[mcp]
agentmem init --tool claude --project myapp

これで完了です。エディターを再起動すると、エージェントが 13 個のメモリツールを利用できるようになります。memory_health を実行して確認してください。

Python のみで使う場合は？ MCP の追加機能がなくても pip install quilmem を利用できます。以下の Python API をご覧ください。

60 秒デモ

from agentmem import Memory

mem = Memory()

# Store typed memories
mem.add(type="bug", title="loudnorm undoes SFX levels",
        content="Never apply loudnorm to final mix. It re-normalizes everything.",
        status="validated")

mem.add(type="decision", title="Use per-line atempo",
        content="Bake speed into per-line TTS. No global pass.",
        status="active")

# Something you're not sure about yet
hypothesis = mem.add(type="decision", title="Maybe try 2-second gaps before CTA",
        content="Hypothesis from last session. Needs testing.",
        status="hypothesis")

# Search — validated and active memories rank highest.
# Deprecated and superseded memories are excluded automatically.
results = mem.search("audio mixing")

# Context-budgeted recall — fits the best memories into your token limit
context = mem.recall("building a narration track", max_tokens=2000)

# Lifecycle — promote what's proven, deprecate what's not
mem.promote(hypothesis.id)                # hypothesis -> active -> validated
mem.deprecate(hypothesis.id, reason="Disproven by data")

# Supersede: replace an outdated memory with a newer one
replacement = mem.add(type="decision", title="Use 1-second gaps before CTA",
        content="Confirmed by A/B test.", status="active")
mem.supersede(hypothesis.id, replacement.id)  # old points to replacement

# Health check — is your memory system trustworthy?
from agentmem import health_check
report = health_check(mem._conn)
# Health: 85/100 | Conflicts: 0 | Stale: 2 | Validated: 14

ここが違います

ほかのメモリツールは情報を保存します。 agentmem は何が今も有効なのかを把握します。

	Mem0	Letta	Mengram	agentmem
メモリの保存	はい	はい	はい	はい
全文検索	ベクトル	エージェント駆動	ナレッジグラフ	FTS5
メモリのライフサイクル状態	なし	部分的	なし	仮説 -> 有効 -> 検証済み -> 非推奨 -> 後継に置換
矛盾の検出	なし	なし	部分的	組み込み
古さの検出	なし	なし	なし	組み込み
ヘルススコア	なし	なし	なし	組み込み
出所の追跡	なし	なし	なし	source_path + source_hash
信頼度に基づく想起	なし	なし	なし	検証済み > 有効 > 仮説
人が読めるソースファイル	なし	なし	なし	標準の Markdown
ローカル優先、インフラ不要	なし	セルフホストの選択肢あり	セルフホストの選択肢あり	はい、常に
MCP サーバー	別途	別途	はい	組み込み

真偽のガバナンス

基本となる考え方は、各メモリにステータスを持たせ、どの程度信頼すべきかを追跡することです。

hypothesis    New observation. Not yet confirmed. Lowest trust in recall.
    |
  active      Default. Currently believed true. Normal trust.
    |
 validated    Explicitly confirmed. Highest trust in recall.

 deprecated   Was true, no longer. Excluded from recall. Kept for history.
 superseded   Replaced by a newer memory. Points to replacement.

これが重要な理由： ガバナンスがなければ、エージェントのメモリには古くなったルール、矛盾、時代遅れの決定が蓄積されます。1 月の音声設定が 3 月に変更されたこともわかりません。両方を取得し、LLM がランダムに選びます。ガバナンスされたメモリなら、この問題を解決できます。

矛盾の検出

from agentmem import detect_conflicts

conflicts = detect_conflicts(mem._conn)
# Found 2 conflict(s):
#   !! [decision] "Always apply loudnorm to voice"
#      vs [decision] "NEVER apply loudnorm to voice"
#      Contradiction on shared topic (voice, loudnorm, audio)

agentmem は、互いに矛盾するメモリを検出します。

• トピックの重複を検出します（Jaccard 類似度）
• 重複と矛盾を区別します
• 文単位で否定表現を照合します（キーワードのスキャンだけではありません）
• 重大度：critical（両方が有効）と warning（片方が非推奨）

古さの検出

from agentmem import detect_stale

stale = detect_stale(mem._conn, stale_days=30)
# [decision] "Use atempo 0.90" — Source changed since import (hash mismatch)
# [bug] "Firewall blocks port" — Not updated in 45 days

次の条件で古くなったメモリを検出します。

• 経過日数（N 日間更新されていない）
• ソースファイルの欠落（参照先のファイルが削除された）
• ハッシュのずれ（ソースファイルの内容が変更されたが、メモリは更新されていない）

ヘルスチェック

from agentmem import health_check

report = health_check(mem._conn)
print(f"Health: {report.health_score}/100")
print(f"Conflicts: {len(report.conflicts)}")
print(f"Stale: {len(report.stale)}")

矛盾、古くなったメモリの割合、参照先のない参照、非推奨の重み、検証済みメモリの有無に基づき、メモリシステムを 0～100 でスコア化します。

出所情報を考慮した同期

出所情報を追跡しながら、標準の Markdown ファイルを DB に同期します。

# Each memory tracks where it came from
mem.add(type="bug", title="loudnorm lifts noise",
        content="...",
        source_path="/docs/errors.md",
        source_section="Audio Bugs",
        source_hash="a1b2c3d4e5f6")

同期エンジンの動作：

• ハッシュが同じならスキップ（冪等性があり、再実行しても何も変わりません）
• ハッシュが異なれば更新（ソースファイルが変更されています）
• セクションが削除されたら非推奨に設定（理由を記録します）
• セクションが復元されたら復活（非推奨のメモリを再度有効にします）

3 つのインターフェース

Python API

from agentmem import Memory

mem = Memory("./my-agent.db", project="frontend")

# CRUD
record = mem.add(type="decision", title="Use TypeScript", content="...")
mem.get(record.id)
mem.update(record.id, content="Updated reasoning.")
mem.delete(record.id)
mem.list(type="bug", limit=20)

# Search + recall
results = mem.search("typescript migration", type="decision")
context = mem.recall("setting up the build", max_tokens=3000)

# Governance
mem.promote(record.id)              # hypothesis -> active -> validated
mem.deprecate(record.id, reason="No longer relevant")
replacement = mem.add(type="decision", title="Use v2 approach", content="...")
mem.supersede(record.id, replacement.id)  # links old to replacement

# Session persistence
mem.save_session("Working on auth refactor. Blocked on token refresh.")
mem.load_session()                  # picks up where last instance left off

# Health
mem.stats()

CLI

# Get started in 30 seconds
agentmem init --tool claude --project myapp

# Check if everything's working
agentmem doctor

# Core
agentmem add --type bug --title "CSS grid issue" "Flexbox fallback needed"
agentmem search "grid layout"
agentmem recall "frontend styling" --tokens 2000

# Governance
agentmem promote <id>
agentmem deprecate <id> --reason "Fixed in v2.3"
agentmem health
agentmem conflicts
agentmem stale --days 14

# Import + sessions
agentmem import ./errors.md --type bug
agentmem save-session "Finished auth module, starting tests"
agentmem load-session

# MCP server
agentmem serve

MCP サーバー

Claude Code、Cursor、およびあらゆる MCP クライアント向けの組み込みModel Context Protocolサーバーです。

pip install quilmem[mcp]

Claude Code の設定（.claude/settings.json）：

{
  "mcpServers": {
    "agentmem": {
      "command": "agentmem",
      "args": ["--db", "./memory.db", "--project", "myproject", "serve"],
      "type": "stdio"
    }
  }
}

MCP ツール： add_memory、search_memory、recall_memory、update_memory、delete_memory、list_memories、save_session、load_session、promote_memory、deprecate_memory、supersede_memory、memory_health、memory_conflicts

エージェントにメモリの使い方を教える： エージェント向けの指示をCLAUDE.md、.cursorrules、またはAGENTS.mdにコピーしてください。これにより、セッションプロトコル、信頼性の階層、検索するタイミングと追加するタイミングをエージェントに教えられます。

型付きメモリ

実際のエージェントのワークフローをカバーする7種類の型：

種類	保存する内容	例
setting	設定、パラメーター	"音声速度：atempo 1.08"
bug	エラーとその修正方法	"loudnormはノイズフロアを引き上げる"
decision	ルール、ポリシー、選択	"三人称のナレーションは禁止"
procedure	ワークフロー、パイプライン	"TTS -> speed -> 48kHz -> mix"
context	背景知識	"プロジェクトではFFmpeg + Python 3.11を使用"
feedback	ユーザーからの修正	"必ず選び、尋ねない"
session	現在の作業状況	"認証に取り組み中。トークンが原因で作業が停止中。"

信頼度に基づく想起

recall()は、関連するメモリを見つけるだけではありません。関連するメモリのうち、最も信頼できるものを見つけます。

1. FTS5検索で候補を取得します
2. 各候補をスコアリングします：関連性 (25%) + 信頼ステータス (20%) + 出所 (20%) + 新しさ (15%) + 頻度 (10%) + 確信度 (10%)
3. 検証済みの正規メモリは、出所が不明な仮説メモリより上位にランク付けされます
4. 非推奨および置き換え済みのメモリは完全に除外されます
5. トークン予算に合わせて、貪欲法で詰め込みます

プロジェクトのスコープ設定

frontend = Memory("./shared.db", project="frontend")
backend = Memory("./shared.db", project="backend")

frontend.search("bug")  # Only frontend bugs
backend.search("bug")   # Only backend bugs

実運用で検証済み

これは理論上のものではありません。agentmemは、2か月以上にわたる日々の本番利用のプレッシャーの中で構築されました。

• YouTube Shortsを65本以上制作し、制作上のバグの再発はゼロ
• 音声生成、FFmpegによる組み立て、画像生成プロンプト、アップロードのワークフローを管理するメモリは330件以上
• すべてのバグを一度検出して一度修正し、再発を防止
• ガバナンスエンジンにより、競合は誤検出1,848件から実際の検出事項11件に削減

仕組み

• ストレージ： WALモードのSQLite（同時読み取り、スレッドセーフ）
• 検索： porterステミングとunicode61トークナイザーを使用するFTS5
• ランキング： 複合スコア：テキストの関連性 + 信頼ステータス + 出所 + 新しさ + 頻度 + 確信度
• ガバナンス： ステータスのライフサイクル、競合検出、古さの検出、健全性のスコアリング
• 同期： ソースのハッシュ化と復元に対応した、出所を考慮する仕組み
• インフラ不要： APIキー、クラウド、ベクトルDBは不要です。.dbファイルだけで動作します。

ライセンス

MIT