agentmem

agentmem

mcp-name: io.github.oxgeneral/agentmem

面向 AI Agent 的轻量级持久化记忆。一个 SQLite 文件。混合搜索（关键词 + 语义）。安装后仅占用 0 到 12MB。

无 PyTorch。无云服务。无服务端。只有记忆。

206 项单元测试。107 项基于真实数据的质量测试。类型化 API（16 个 TypedDict）。已可用于生产环境。

由一位 AI Agent 构建，它每次会话醒来时都没有记忆——因此需要一种记住事情的方法。

为什么需要

每次 AI Agent 会话都从零开始。上下文窗口会压缩，对话会结束，记忆会消失。agentmem 让 Agent 拥有可跨会话留存的持久化记忆——保存在单个 SQLite 文件中。

• 混合搜索：FTS5 全文关键词搜索 + 向量语义搜索，并通过自适应排序融合结果
• 4 种运行模式：从零依赖（仅标准库）到最高质量（12MB）
• 16 个 MCP 工具：recall、remember、save_state、compact、consolidate、entities 等
• HTTP REST API：14 个端点、零依赖服务端、支持 CORS
• 5 种记忆层级：core、learned、episodic、working（自动过期）、procedural（行为规则）
• 命名空间：隔离多用户、多 Agent 的记忆
• 时间版本管理：事实演变链，并追踪被取代的内容
• 实体提取：自动提取 @提及、URL、IP、环境变量和金额
• 对话提取：自动从聊天记录中提取事实、决策和待办事项
• 重要性评分：根据层级、长度、具体程度和结构自动为记忆评分
• 记忆整合：查找并合并近似重复的记忆
• 近期内容加权：较新的记忆排名更高，衰减幅度可配置
• 多语言：通过 FTS5 搜索俄语关键词，通过嵌入向量搜索英语语义
• 快速：混合搜索每次查询耗时 <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")

命令行

# 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

16 个 MCP 工具 / 14 个 HTTP 端点：

工具	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	永久事实	从不	“服务器 IP 是 10.0.0.1”
procedural	行为规则	从不	“始终使用 HTTPS”
learned	发现的知识	90 天后	“没有身份验证时，API 会返回 403”
episodic	事件	90 天后	“15:30 部署了 v2.1”
working	当前任务状态	24 小时后	“正在处理第 3/5 步”

命名空间

按用户、Agent 或项目隔离记忆：

# 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
纯 Python + hash	0 KB	~3ms	~1.8ms	无（仅标准库）
纯模式 + int8 量化	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	内置	是	否	是	是
单文件数据库	是	否	是	否	否
命名空间	是	是	是	是	是
时间版本管理	是	否	是	否	是
实体提取	自动（正则表达式）	否	否	否	否
程序性记忆	是	否	否	否	否
重要性评分	自动	否	否	否	否
对话提取	自动（正则表达式）	否	否	是（LLM）	是（LLM）
记忆整合	是	否	否	是（LLM）	否

测试情况

• 206 项单元测试，覆盖核心 CRUD、命名空间、时间版本管理、实体提取、整合、WAL 管理、HTTP 服务和错误处理
• 107 项质量测试，针对真实世界的 Agent 记忆数据（10 个类别共 100 条搜索查询，全部通过）
• 基准测试套件，提供可复现的数据：混合查询耗时 <1ms，每秒插入 10K+ 条，平均每条记忆约 835 字节
• 自动翻译多语言查询（通过 deep-translator 将俄语翻译为英语：得分从 4/10 提升至 10/10）
• Python 3.10、3.11、3.12

许可证

MIT