{
  "markdown": "# agentmem\n\nmcp-name: io.github.oxgeneral/agentmem\n\nLightweight persistent memory for AI agents. One SQLite file. Hybrid search (keywords + semantics). Zero to 12MB install.\n\nNo PyTorch. No cloud. No server. Just memory.\n\n**206 unit tests. 107 quality tests on real data. Typed API (16 TypedDict). Production-ready.**\n\n> Built by an AI agent that wakes up with no memory every session — and needed a way to remember.\n\n## Why\n\nEvery AI agent session starts from zero. Context windows compress, conversations end, memory vanishes. `agentmem` gives agents persistent memory that survives across sessions — in a single SQLite file.\n\n- **Hybrid search**: FTS5 full-text keywords + vector semantic search, fused with adaptive ranking\n- **4 operational modes**: from zero dependencies (stdlib only) to best quality (12MB)\n- **16 MCP tools**: recall, remember, save_state, compact, consolidate, entities, and more\n- **HTTP REST API**: 14 endpoints, zero-dependency server, CORS-ready\n- **5 memory tiers**: core, learned, episodic, working (auto-expires), procedural (behavioral rules)\n- **Namespaces**: multi-user, multi-agent memory isolation\n- **Temporal versioning**: fact evolution chains with supersedes tracking\n- **Entity extraction**: auto-extracts @mentions, URLs, IPs, env vars, money amounts\n- **Conversation extraction**: auto-extracts facts, decisions, TODOs from chat history\n- **Importance scoring**: auto-scores memories by tier, length, specificity, structure\n- **Memory consolidation**: finds and merges near-duplicate memories\n- **Recency boost**: newer memories rank higher with configurable decay\n- **Multilingual**: Russian keywords via FTS5, English semantics via embeddings\n- **Fast**: <1ms/query hybrid search, <5ms cold start, <0.2ms/chunk import\n\n## Install\n\n```bash\n# Best quality (sqlite-vec + model2vec, 12MB total)\npip install agentmem-lite[all]\n\n# Minimal (sqlite-vec + hash embeddings, 151KB)\npip install agentmem-lite\n\n# Zero dependencies (pure Python, stdlib only)\npip install agentmem-lite --no-deps\n\n# From source\ngit clone https://github.com/oxgeneral/agentmem && cd agentmem\npip install -e \".[all]\"\n```\n\n## Quick Start\n\n### Python API\n\n```python\nfrom agentmem import MemoryStore, get_embedding_model\n\n# Auto-selects best available backend\nembed = get_embedding_model()\nstore = MemoryStore(\"memory.db\", embedding_dim=embed.dim)\nstore.set_embed_fn(embed)\n\n# Store memories with namespaces\nstore.remember(\"Server costs $50/month\", tier=\"core\", namespace=\"infra\")\nstore.remember(\"API returns 403 without auth\", tier=\"learned\", namespace=\"api\")\nstore.remember(\"Deployed v2.1 at 15:30\", tier=\"episodic\")\n\n# Search — hybrid keyword + semantic, with recency boost\nresults = store.recall(\"server costs\", recency_weight=0.15)\n\n# Namespace isolation\nresults = store.recall(\"server\", namespace=\"infra\")\n\n# Save working state before context compression\nstore.save_state(\"Working on auth fix, step 3/5, blocked by CORS\")\n\n# Add behavioral rules (procedural memory)\nstore.add_procedure(\"Always use HTTPS in production\")\nstore.add_procedure(\"Never expose debug endpoints\")\nrules = store.get_procedures()  # → formatted for system prompt\n\n# Update facts with version chain\nstore.update_memory(old_id=1, new_content=\"Server costs $75/month\")\nhistory = store.history(memory_id=2)  # → trace fact evolution\n\n# Find related memories by entity\nrelated = store.related(\"10.0.0.1\")  # → all memories mentioning this IP\nentities = store.entities(entity_type=\"ip\")  # → list all known IPs\n\n# Auto-extract from conversations\nmessages = [\n    {\"role\": \"user\", \"content\": \"Set API_KEY to sk-abc123. Always validate input.\"},\n    {\"role\": \"assistant\", \"content\": \"Noted. I decided to use pydantic for validation.\"},\n]\nresult = store.process_conversation(messages, namespace=\"project\")\n# → extracts config, preferences, decisions automatically\n\n# Maintenance\nstore.compact(max_age_days=90)  # archive old low-value memories\nstore.consolidate(similarity_threshold=0.85)  # merge near-duplicates\n\n# Import markdown files\nstore.import_markdown(\"MEMORY.md\", tier=\"core\")\n```\n\n### CLI\n\n```bash\n# Initialize database\nagentmem init --db memory.db\n\n# Import markdown files\nagentmem import MEMORY.md --tier core -n my-agent\nagentmem import-dir ./daily-logs/ --tier episodic\n\n# Search with namespace filter\nagentmem search \"deployment process\" --limit 5 -n infra\n\n# Manage procedures\nagentmem add-procedure \"Always use markdown formatting\"\nagentmem procedures\n\n# View entities and relations\nagentmem entities --type ip\nagentmem related 10.0.0.1\n\n# Maintenance\nagentmem compact --max-age-days 90 --dry-run\nagentmem consolidate --threshold 0.85\n\n# Process conversation\nagentmem process chat.json -n project\n\n# Stats and export\nagentmem stats\nagentmem export --tier core\n```\n\n### MCP Server (stdio)\n\n```bash\npython -m agentmem --db memory.db\n```\n\nAdd to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"memory\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"agentmem\", \"--db\", \"/path/to/memory.db\"]\n    }\n  }\n}\n```\n\n### HTTP REST API\n\n```bash\n# Start HTTP server\nagentmem serve-http --port 8422\n\n# Or directly\nagentmem-http --port 8422 --db memory.db\n```\n\n```bash\n# Store a memory\ncurl -X POST http://localhost:8422/remember \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\": \"Server IP is 10.0.0.1\", \"tier\": \"core\", \"namespace\": \"infra\"}'\n\n# Search\ncurl \"http://localhost:8422/recall?query=server+IP&namespace=infra\"\n\n# Health check\ncurl http://localhost:8422/health\n```\n\n**16 MCP tools / 14 HTTP endpoints:**\n\n| Tool | HTTP | Description |\n|------|------|-------------|\n| `recall` | `GET /recall` | Hybrid keyword + semantic search |\n| `remember` | `POST /remember` | Store a new memory |\n| `save_state` | `POST /save_state` | Emergency save before context compression |\n| `today` | `GET /today` | Get all memories from today |\n| `forget` | `POST /forget` | Archive a memory (soft delete) |\n| `unarchive` | `POST /unarchive` | Restore an archived memory |\n| `stats` | `GET /stats` | Memory statistics and health |\n| `compact` | `POST /compact` | Archive low-value memories |\n| `consolidate` | `POST /consolidate` | Merge near-duplicate memories |\n| `update_memory` | `POST /update_memory` | Replace a memory with version chain |\n| `history` | `GET /history` | Trace fact version history |\n| `related` | `GET /related` | Find memories by entity |\n| `entities` | `GET /entities` | List all extracted entities |\n| `get_procedures` | — | Get behavioral rules for system prompt |\n| `add_procedure` | — | Add a behavioral rule |\n| `process_conversation` | — | Auto-extract from chat history |\n\n## Memory Tiers\n\n| Tier | Purpose | Auto-compacted | Example |\n|------|---------|---------------|---------|\n| `core` | Permanent facts | Never | \"Server IP is 10.0.0.1\" |\n| `procedural` | Behavioral rules | Never | \"Always use HTTPS\" |\n| `learned` | Discovered knowledge | After 90 days | \"API returns 403 without auth\" |\n| `episodic` | Events | After 90 days | \"Deployed v2.1 at 15:30\" |\n| `working` | Current task state | After 24 hours | \"Working on step 3/5\" |\n\n## Namespaces\n\nIsolate memories per user, agent, or project:\n\n```python\n# Store in namespaces\nstore.remember(\"Alice's API key\", namespace=\"user/alice\")\nstore.remember(\"Bob's config\", namespace=\"user/bob\")\nstore.remember(\"Shared fact\", namespace=\"team\")\n\n# Search within namespace (prefix matching)\nstore.recall(\"API\", namespace=\"user/alice\")  # only Alice's memories\nstore.recall(\"API\", namespace=\"user\")  # Alice + Bob (prefix match)\nstore.recall(\"API\")  # everything\n```\n\n## Temporal Versioning\n\nTrack how facts evolve over time:\n\n```python\n# Initial fact\nr1 = store.remember(\"Server costs $50/month\", tier=\"core\")\n\n# Fact changes — old version archived, linked via supersedes\nr2 = store.update_memory(r1[\"id\"], \"Server costs $75/month\")\n\n# Trace the history\nhistory = store.history(r2[\"id\"])\n# → [{\"id\": 2, \"content\": \"...$75...\"}, {\"id\": 1, \"content\": \"...$50...\"}]\n```\n\n## Entity Extraction\n\nAutomatic regex-based NER on every `remember()` call:\n\n| Type | Pattern | Example |\n|------|---------|---------|\n| `mention` | `@username` | @alice |\n| `url` | `https://...` | https://api.example.com |\n| `ip` | `N.N.N.N` | 10.0.0.1 |\n| `port` | `:NNNN` | :8080 |\n| `email` | `user@domain` | admin@example.com |\n| `env_var` | `ALL_CAPS` | OPENAI_API_KEY |\n| `money` | `$NNN` | $50 |\n| `path` | `/unix/path` | /etc/nginx/conf.d |\n| `hashtag` | `#tag` | #deployment |\n\n```python\n# Find all memories mentioning an entity\nstore.related(\"10.0.0.1\")\nstore.related(\"@alice\", entity_type=\"mention\")\n\n# List all known entities\nstore.entities()  # sorted by memory count\nstore.entities(entity_type=\"ip\")\n```\n\n## Conversation Auto-Extraction\n\nAuto-extract memories from chat history (regex-only, no LLM):\n\n```python\nmessages = [\n    {\"role\": \"user\", \"content\": \"Set DATABASE_URL to postgres://localhost/mydb\"},\n    {\"role\": \"assistant\", \"content\": \"I decided to use connection pooling. Important: max 20 connections.\"},\n    {\"role\": \"user\", \"content\": \"Always validate input. TODO: add rate limiting.\"},\n]\nresult = store.process_conversation(messages)\n# Extracts: config→core, decisions→episodic, preferences→procedural, todos→working, important→core\n```\n\n## Operational Modes\n\nagentmem automatically selects the best available mode:\n\n| Mode | Install Size | Init Time | Query Time | Dependencies |\n|------|-------------|-----------|------------|-------------|\n| **sqlite-vec + model2vec** | 12 MB | ~5ms* | ~1ms | sqlite-vec, model2vec, numpy |\n| **sqlite-vec + hash** | 151 KB | ~5ms | ~0.8ms | sqlite-vec |\n| **pure Python + hash** | 0 KB | ~3ms | ~1.8ms | none (stdlib only) |\n| **pure + int8 quantize** | 0 KB | ~3ms | ~3ms | none (stdlib only) |\n\n*\\*With lazy loading — model2vec loads on first query, not on init*\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────┐\n│              MemoryStore                      │\n│  ┌──────────┐  ┌──────────┐  ┌────────────┐  │\n│  │  FTS5    │  │  Vector  │  │  Entity    │  │\n│  │ keywords │  │  Index   │  │  Index     │  │\n│  │ + BM25   │  │ cosine   │  │  regex NER │  │\n│  └────┬─────┘  └────┬─────┘  └─────┬──────┘  │\n│       └──────┬───────┘              │         │\n│    Adaptive Hybrid Scorer           │         │\n│  (query classify + recency +        │         │\n│   importance boost)                 │         │\n│  ┌──────────────────────────────────┴───────┐ │\n│  │            SQLite + WAL                  │ │\n│  │  memories │ memories_fts │ vecs │ entities│ │\n│  └──────────────────────────────────────────┘ │\n│            One file: memory.db                │\n└───────────────────────────────────────────────┘\n```\n\n## Comparison\n\n| Feature | agentmem | ChromaDB | LanceDB | mem0 | Zep |\n|---------|----------|----------|---------|------|-----|\n| Install size | 0-12 MB | 400+ MB | 100+ MB | 500+ MB | Cloud |\n| Cold start | 3-5 ms | seconds | seconds | seconds | N/A |\n| PyTorch required | No | Yes | No | Yes | N/A |\n| Cloud required | No | No | No | Yes | Yes |\n| Zero-dep mode | Yes | No | No | No | No |\n| Keyword search | FTS5 (BM25) | No | No | No | Yes |\n| MCP server | 16 tools | No | No | Yes | No |\n| HTTP API | Built-in | Yes | No | Yes | Yes |\n| Single file DB | Yes | No | Yes | No | No |\n| Namespaces | Yes | Yes | Yes | Yes | Yes |\n| Temporal versioning | Yes | No | Yes | No | Yes |\n| Entity extraction | Auto (regex) | No | No | No | No |\n| Procedural memory | Yes | No | No | No | No |\n| Importance scoring | Auto | No | No | No | No |\n| Conversation extraction | Auto (regex) | No | No | Yes (LLM) | Yes (LLM) |\n| Memory consolidation | Yes | No | No | Yes (LLM) | No |\n\n## Tested\n\n- **206 unit tests** covering core CRUD, namespaces, temporal versioning, entity extraction, consolidation, WAL management, HTTP server, error handling\n- **107 quality tests** against real-world agent memory data (100 search queries across 10 categories, all passing)\n- **Benchmark suite** with reproducible numbers: <1ms hybrid query, 10K+ inserts/sec, ~835 bytes/memory\n- **Auto-translate** for multilingual queries (Russian → English via deep-translator: 4/10 → 10/10)\n- Python 3.10, 3.11, 3.12\n\n## License\n\nMIT\n",
  "bytes": 12145,
  "sha": "8cdcc64b1a7e8dfd600371edf0ceefd7f1c870efc8352e76d3dc792761426aba",
  "repo_slug": "oxgeneral/agentmem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_oxgeneral_agentmem_5600378a/readme"
}