agentmem

what is agentmem?

agentmem is a lightweight persistent-memory MCP (memory control plane) for AI agents that stores agent memories in a single SQLite file. It combines hybrid search (FTS5 keyword/BM25 + vector/semantic search), temporal versioning, namespaces, entity extraction, multiple memory tiers, and an MCP/HTTP API — all designed to run locally with zero-to-small dependencies (0–12 MB install).

how to use agentmem?

• Install: pip install agentmem-lite[all] (best quality), agentmem-lite (minimal), or --no-deps for stdlib-only. From source via pip install -e .
• Python API: instantiate MemoryStore(memory.db, embedding_dim=…), set an embed function, then store with store.remember(…), query with store.recall(…), update with store.update_memory(…), and manage procedures/entities via add_procedure(), entities(), related(), etc.
• CLI: agentmem init/import/search/compact/consolidate/procedures/stats and agentmem serve-http to run a local HTTP API. Also supports MCP stdio server (python -m agentmem) for integration with MCP clients.
• HTTP API: built-in endpoints (GET /recall, POST /remember, /compact, /consolidate, /history, /entities, etc.) for remote/local access.

key features

• Hybrid search: fused FTS5 (keywords, BM25) + vector semantic search with adaptive ranking and recency/importance boosts
• Five memory tiers: core, procedural, learned, episodic, working (auto-expire rules)
• Namespaces for multi-user/multi-agent isolation (prefix matching supported)
• Temporal versioning and fact evolution (supersedes chains + history tracing)
• Automatic entity extraction (regex-based NER: mentions, URLs, IPs, env vars, money, paths, hashtags)
• Conversation auto-extraction (regex-driven extraction of config, decisions, TODOs, etc.)
• Memory consolidation (merge near-duplicates), compaction, importance scoring, recency decay
• Multiple operational modes: zero-dep pure-Python up to sqlite-vec + model2vec (best quality) with tiny install size
• Fast: sub-ms hybrid queries, low cold-start times, high insert throughput
• 16 MCP tools and 14 HTTP endpoints; one SQLite DB file (memory.db)

use cases

1. Give AI agents persistent memory across sessions (retain facts, rules, events)
2. Multi-agent or multi-user systems that need isolated memories per namespace
3. Local semantic+keyword knowledge store for tooling, bots, or automation without cloud or heavy ML frameworks
4. Configuration, secrets/environment tracking, auditing and versioned fact history for operations
5. Fast local retrieval for assistant prompts, system rules (procedural memory), and task/working-state persistence

FAQ

• Does agentmem require cloud or PyTorch? No. It runs locally, supports a zero-dependency mode, and does not require PyTorch or cloud services.

• How large is the install and what are the modes? Modes range from pure stdlib (0 KB) to sqlite-vec + model2vec (~12 MB). A minimal sqlite-vec + hash mode is ~151 KB.

• Where is data stored? In a single SQLite file (memory.db) with WAL; memories, FTS tables, vector index and entity tables live in that file.

• Are embeddings / semantic search supported and required? Yes — semantic search is supported via pluggable embedding backends (model2vec, hash-based fallbacks). You can run pure keyword-only if preferred.

• Is entity extraction or conversation parsing done via LLMs? No — entity extraction and conversation auto-extraction are regex-based (no LLM required).

• How do I update or version facts? Use update_memory(old_id, new_content) to create a new version linked via supersedes; trace with history(memory_id).

• Is this production-ready? The project reports 206 unit tests, 107 quality tests on real data, benchmarks, and support for Python 3.10–3.12.

• How do I run it as a server? Use agentmem serve-http --port <n> or run python -m agentmem --db memory.db for stdio MCP integration.