agentmem

agentmem

mcp-name: io.github.oxgeneral/agentmem

AI エージェント向けの軽量な永続メモリです。SQLite ファイルは 1 つ。ハイブリッド検索（キーワード＋セマンティック検索）。インストールサイズは 12MB 以下です。

PyTorch もクラウドもサーバーも不要です。メモリだけです。

ユニットテスト 206 件。実データを使った品質テスト 107 件。型付き API（TypedDict 16 種）。本番環境対応。

セッションごとに記憶なしで起動する AI エージェントが、記憶する方法を必要として開発しました。

理由

AI エージェントのセッションは毎回ゼロから始まります。コンテキストウィンドウは圧縮され、会話は終わり、記憶は消えてしまいます。agentmem は、1 つの SQLite ファイルにセッションをまたいで保持される永続メモリをエージェントに提供します。

• ハイブリッド検索：FTS5 全文キーワード検索＋ベクトルセマンティック検索を、適応型ランキングで統合
• 4 つの動作モード：依存関係ゼロ（標準ライブラリのみ）から最高品質（12MB）まで
• MCP ツール 16 種：recall、remember、save_state、compact、consolidate、entities など
• HTTP REST API：エンドポイント 14 個、依存関係ゼロのサーバー、CORS 対応
• メモリ階層 5 種：core、learned、episodic、working（自動期限切れ）、procedural（動作ルール）
• 名前空間：複数ユーザー・複数エージェント間のメモリ分離
• 時間的バージョニング：上書き追跡付きの事実の変遷チェーン
• エンティティ抽出：@メンション、URL、IP、環境変数、金額を自動抽出
• 会話抽出：チャット履歴から事実、決定事項、TODO を自動抽出
• 重要度スコアリング：階層、長さ、具体性、構造に基づいてメモリを自動スコアリング
• メモリの統合：類似度の高いメモリを検出して統合
• 新しさによる加点：設定可能な減衰率に基づき、新しいメモリほど上位に表示
• 多言語対応：FTS5 によるロシア語キーワード検索、埋め込みによる英語セマンティック検索
• 高速：ハイブリッド検索は 1 回あたり <1ms、コールドスタートは <5ms、チャンクのインポートは <0.2ms

インストール

# Best quality (sqlite-vec + model2vec, 12MB total)
pip install agentmem-lite[all]

# Minimal (sqlite-vec + hash embeddings, 151KB)
pip install agentmem-lite

# Zero dependencies (pure Python, stdlib only)
pip install agentmem-lite --no-deps

# From source
git clone https://github.com/oxgeneral/agentmem && cd agentmem
pip install -e ".[all]"

クイックスタート

Python API

from agentmem import MemoryStore, get_embedding_model

# Auto-selects best available backend
embed = get_embedding_model()
store = MemoryStore("memory.db", embedding_dim=embed.dim)
store.set_embed_fn(embed)

# Store memories with namespaces
store.remember("Server costs $50/month", tier="core", namespace="infra")
store.remember("API returns 403 without auth", tier="learned", namespace="api")
store.remember("Deployed v2.1 at 15:30", tier="episodic")

# Search — hybrid keyword + semantic, with recency boost
results = store.recall("server costs", recency_weight=0.15)

# Namespace isolation
results = store.recall("server", namespace="infra")

# Save working state before context compression
store.save_state("Working on auth fix, step 3/5, blocked by CORS")

# Add behavioral rules (procedural memory)
store.add_procedure("Always use HTTPS in production")
store.add_procedure("Never expose debug endpoints")
rules = store.get_procedures()  # → formatted for system prompt

# Update facts with version chain
store.update_memory(old_id=1, new_content="Server costs $75/month")
history = store.history(memory_id=2)  # → trace fact evolution

# Find related memories by entity
related = store.related("10.0.0.1")  # → all memories mentioning this IP
entities = store.entities(entity_type="ip")  # → list all known IPs

# Auto-extract from conversations
messages = [
    {"role": "user", "content": "Set API_KEY to sk-abc123. Always validate input."},
    {"role": "assistant", "content": "Noted. I decided to use pydantic for validation."},
]
result = store.process_conversation(messages, namespace="project")
# → extracts config, preferences, decisions automatically

# Maintenance
store.compact(max_age_days=90)  # archive old low-value memories
store.consolidate(similarity_threshold=0.85)  # merge near-duplicates

# Import markdown files
store.import_markdown("MEMORY.md", tier="core")

CLI

# Initialize database
agentmem init --db memory.db

# Import markdown files
agentmem import MEMORY.md --tier core -n my-agent
agentmem import-dir ./daily-logs/ --tier episodic

# Search with namespace filter
agentmem search "deployment process" --limit 5 -n infra

# Manage procedures
agentmem add-procedure "Always use markdown formatting"
agentmem procedures

# View entities and relations
agentmem entities --type ip
agentmem related 10.0.0.1

# Maintenance
agentmem compact --max-age-days 90 --dry-run
agentmem consolidate --threshold 0.85

# Process conversation
agentmem process chat.json -n project

# Stats and export
agentmem stats
agentmem export --tier core

MCP サーバー（stdio）

python -m agentmem --db memory.db

MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-m", "agentmem", "--db", "/path/to/memory.db"]
    }
  }
}

HTTP REST API

# Start HTTP server
agentmem serve-http --port 8422

# Or directly
agentmem-http --port 8422 --db memory.db

# Store a memory
curl -X POST http://localhost:8422/remember \
  -H "Content-Type: application/json" \
  -d '{"content": "Server IP is 10.0.0.1", "tier": "core", "namespace": "infra"}'

# Search
curl "http://localhost:8422/recall?query=server+IP&namespace=infra"

# Health check
curl http://localhost:8422/health

MCP ツール 16 個／HTTP エンドポイント 14 個：

ツール	HTTP	説明
recall	GET /recall	キーワード＋セマンティックのハイブリッド検索
remember	POST /remember	新しいメモリを保存
save_state	POST /save_state	コンテキスト圧縮前の緊急保存
today	GET /today	今日のメモリをすべて取得
forget	POST /forget	メモリをアーカイブ（ソフト削除）
unarchive	POST /unarchive	アーカイブしたメモリを復元
stats	GET /stats	メモリの統計情報と健全性
compact	POST /compact	価値の低いメモリをアーカイブ
consolidate	POST /consolidate	類似度の高いメモリを統合
update_memory	POST /update_memory	バージョンチェーン付きでメモリを置換
history	GET /history	事実のバージョン履歴を追跡
related	GET /related	エンティティからメモリを検索
entities	GET /entities	抽出されたエンティティをすべて一覧表示
get_procedures	—	システムプロンプト用の動作ルールを取得
add_procedure	—	動作ルールを追加
process_conversation	—	チャット履歴から自動抽出

メモリ階層

階層	用途	自動整理	例
core	永続的な事実	なし	"Server IP is 10.0.0.1"
procedural	動作ルール	なし	"Always use HTTPS"
learned	発見した知識	90 日後	"API returns 403 without auth"
episodic	出来事	90 日後	"Deployed v2.1 at 15:30"
working	現在のタスク状態	24 時間後	"Working on step 3/5"

名前空間

ユーザー、エージェント、プロジェクトごとにメモリを分離します。

# Store in namespaces
store.remember("Alice's API key", namespace="user/alice")
store.remember("Bob's config", namespace="user/bob")
store.remember("Shared fact", namespace="team")

# Search within namespace (prefix matching)
store.recall("API", namespace="user/alice")  # only Alice's memories
store.recall("API", namespace="user")  # Alice + Bob (prefix match)
store.recall("API")  # everything

時間的バージョニング

事実が時間とともにどのように変化するかを追跡します。

# Initial fact
r1 = store.remember("Server costs $50/month", tier="core")

# Fact changes — old version archived, linked via supersedes
r2 = store.update_memory(r1["id"], "Server costs $75/month")

# Trace the history
history = store.history(r2["id"])
# → [{"id": 2, "content": "...$75..."}, {"id": 1, "content": "...$50..."}]

エンティティ抽出

remember() が呼び出されるたびに、正規表現ベースの NER で自動抽出します。

種類	パターン	例
mention	@username	@alice
url	https://...	https://api.example.com
ip	N.N.N.N	10.0.0.1
port	:NNNN	:8080
email	user@domain	[email protected]
env_var	ALL_CAPS	OPENAI_API_KEY
money	$NNN	$50
path	/unix/path	/etc/nginx/conf.d
hashtag	#tag	#deployment

# Find all memories mentioning an entity
store.related("10.0.0.1")
store.related("@alice", entity_type="mention")

# List all known entities
store.entities()  # sorted by memory count
store.entities(entity_type="ip")

会話からの自動抽出

チャット履歴からメモリを自動抽出します（正規表現のみ、LLM は使用しません）。

messages = [
    {"role": "user", "content": "Set DATABASE_URL to postgres://localhost/mydb"},
    {"role": "assistant", "content": "I decided to use connection pooling. Important: max 20 connections."},
    {"role": "user", "content": "Always validate input. TODO: add rate limiting."},
]
result = store.process_conversation(messages)
# Extracts: config→core, decisions→episodic, preferences→procedural, todos→working, important→core

動作モード

agentmem は、利用可能な最適なモードを自動的に選択します。

モード	インストールサイズ	初期化時間	クエリ時間	依存関係
sqlite-vec + model2vec	12 MB	~5ms*	~1ms	sqlite-vec, model2vec, numpy
sqlite-vec + hash	151 KB	~5ms	~0.8ms	sqlite-vec
pure Python + hash	0 KB	~3ms	~1.8ms	なし（標準ライブラリのみ）
pure + int8 quantize	0 KB	~3ms	~3ms	なし（標準ライブラリのみ）

*遅延読み込みの場合 — model2vec は初期化時ではなく、最初のクエリ時に読み込まれます

アーキテクチャ

┌──────────────────────────────────────────────┐
│              MemoryStore                      │
│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
│  │  FTS5    │  │  Vector  │  │  Entity    │  │
│  │ keywords │  │  Index   │  │  Index     │  │
│  │ + BM25   │  │ cosine   │  │  regex NER │  │
│  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │
│       └──────┬───────┘              │         │
│    Adaptive Hybrid Scorer           │         │
│  (query classify + recency +        │         │
│   importance boost)                 │         │
│  ┌──────────────────────────────────┴───────┐ │
│  │            SQLite + WAL                  │ │
│  │  memories │ memories_fts │ vecs │ entities│ │
│  └──────────────────────────────────────────┘ │
│            One file: memory.db                │
└───────────────────────────────────────────────┘

比較

機能	agentmem	ChromaDB	LanceDB	mem0	Zep
インストールサイズ	0-12 MB	400+ MB	100+ MB	500+ MB	クラウド
コールドスタート	3-5 ms	数秒	数秒	数秒	該当なし
PyTorch が必要	いいえ	はい	いいえ	はい	該当なし
クラウドが必要	いいえ	いいえ	いいえ	はい	はい
依存関係ゼロのモード	はい	いいえ	いいえ	いいえ	いいえ
キーワード検索	FTS5 (BM25)	いいえ	いいえ	いいえ	はい
MCP サーバー	16 個のツール	いいえ	いいえ	はい	いいえ
HTTP API	組み込み	はい	いいえ	はい	はい
単一ファイルの DB	はい	いいえ	はい	いいえ	いいえ
名前空間	はい	はい	はい	はい	はい
時系列バージョン管理	はい	いいえ	はい	いいえ	はい
エンティティ抽出	自動（正規表現）	いいえ	いいえ	いいえ	いいえ
手続き的メモリ	はい	いいえ	いいえ	いいえ	いいえ
重要度スコアリング	自動	いいえ	いいえ	いいえ	いいえ
会話からの抽出	自動（正規表現）	いいえ	いいえ	はい（LLM）	はい（LLM）
メモリの統合	はい	いいえ	いいえ	はい（LLM）	いいえ

テスト済み

• 206 件のユニットテストで、コア CRUD、名前空間、時系列バージョン管理、エンティティ抽出、統合、WAL 管理、HTTP サーバー、エラー処理を網羅
• 107 件の品質テストを実際のエージェントメモリデータで実施（10 カテゴリにわたる検索クエリ 100 件、すべて合格）
• ベンチマークスイートで再現可能な数値を測定：ハイブリッドクエリ <1ms、挿入 10K+ 件/秒、メモリあたり約 835 バイト
• 多言語クエリの自動翻訳（deep-translator によるロシア語 → 英語：4/10 → 10/10）
• Python 3.10、3.11、3.12

ライセンス

MIT