Agentmem

agentmem

mcp-name: io.github.oxgeneral/agentmem

Lightweight persistent memory for AI agents. One SQLite file. Hybrid search (keywords + semantics). Zero to 12MB install.

No PyTorch. No cloud. No server. Just memory.

206 unit tests. 107 quality tests on real data. Typed API (16 TypedDict). Production-ready.

> Built by an AI agent that wakes up with no memory every session — and needed a way to remember.

Why

Every 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.

• Hybrid search: FTS5 full-text keywords + vector semantic search, fused with adaptive ranking
• 4 operational modes: from zero dependencies (stdlib only) to best quality (12MB)
• 16 MCP tools: recall, remember, save_state, compact, consolidate, entities, and more
• HTTP REST API: 14 endpoints, zero-dependency server, CORS-ready
• 5 memory tiers: core, learned, episodic, working (auto-expires), procedural (behavioral rules)
• Namespaces: multi-user, multi-agent memory isolation
• Temporal versioning: fact evolution chains with supersedes tracking
• Entity extraction: auto-extracts @mentions, URLs, IPs, env vars, money amounts
• Conversation extraction: auto-extracts facts, decisions, TODOs from chat history
• Importance scoring: auto-scores memories by tier, length, specificity, structure
• Memory consolidation: finds and merges near-duplicate memories
• Recency boost: newer memories rank higher with configurable decay
• Multilingual: Russian keywords via FTS5, English semantics via embeddings
• Fast: <1ms/query hybrid search, <5ms cold start, <0.2ms/chunk import

Install

# 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]"

Quick Start

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 Server (stdio)

python -m agentmem --db memory.db

Add to your MCP client config:

{
  "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 tools / 14 HTTP endpoints:

| Tool | HTTP | Description | |------|------|-------------| | recall | GET /recall | Hybrid keyword + semantic search | | remember | POST /remember | Store a new memory | | save_state | POST /save_state | Emergency save before context compression | | today | GET /today | Get all memories from today | | forget | POST /forget | Archive a memory (soft delete) | | unarchive | POST /unarchive | Restore an archived memory | | stats | GET /stats | Memory statistics and health | | compact | POST /compact | Archive low-value memories | | consolidate | POST /consolidate | Merge near-duplicate memories | | update_memory | POST /update_memory | Replace a memory with version chain | | history | GET /history | Trace fact version history | | related | GET /related | Find memories by entity | | entities | GET /entities | List all extracted entities | | get_procedures | — | Get behavioral rules for system prompt | | add_procedure | — | Add a behavioral rule | | process_conversation | — | Auto-extract from chat history |

Memory Tiers

| Tier | Purpose | Auto-compacted | Example | |------|---------|---------------|---------| | core | Permanent facts | Never | "Server IP is 10.0.0.1" | | procedural | Behavioral rules | Never | "Always use HTTPS" | | learned | Discovered knowledge | After 90 days | "API returns 403 without auth" | | episodic | Events | After 90 days | "Deployed v2.1 at 15:30" | | working | Current task state | After 24 hours | "Working on step 3/5" |

Namespaces

Isolate memories per user, agent, or project:

# 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

Temporal Versioning

Track how facts evolve over time:

# 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..."}]

Entity Extraction

Automatic regex-based NER on every remember() call:

| Type | Pattern | Example | |------|---------|---------| | mention | @username | @alice | | url | https://... | https://api.example.com | | ip | N.N.N.N | 10.0.0.1 | | port | :NNNN | :8080 | | email | user@domain | admin@example.com | | env_var | ALL_CAPS | OPENAIAPIKEY | | 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")

Conversation Auto-Extraction

Auto-extract memories from chat history (regex-only, no 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

Operational Modes

agentmem automatically selects the best available mode:

| Mode | Install Size | Init Time | Query Time | Dependencies | |------|-------------|-----------|------------|-------------| | 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 | none (stdlib only) | | pure + int8 quantize | 0 KB | ~3ms | ~3ms | none (stdlib only) |

\With lazy loading — model2vec loads on first query, not on init*

Architecture

┌──────────────────────────────────────────────┐
│              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                │
└───────────────────────────────────────────────┘

Comparison

| Feature | agentmem | ChromaDB | LanceDB | mem0 | Zep | |---------|----------|----------|---------|------|-----| | Install size | 0-12 MB | 400+ MB | 100+ MB | 500+ MB | Cloud | | Cold start | 3-5 ms | seconds | seconds | seconds | N/A | | PyTorch required | No | Yes | No | Yes | N/A | | Cloud required | No | No | No | Yes | Yes | | Zero-dep mode | Yes | No | No | No | No | | Keyword search | FTS5 (BM25) | No | No | No | Yes | | MCP server | 16 tools | No | No | Yes | No | | HTTP API | Built-in | Yes | No | Yes | Yes | | Single file DB | Yes | No | Yes | No | No | | Namespaces | Yes | Yes | Yes | Yes | Yes | | Temporal versioning | Yes | No | Yes | No | Yes | | Entity extraction | Auto (regex) | No | No | No | No | | Procedural memory | Yes | No | No | No | No | | Importance scoring | Auto | No | No | No | No | | Conversation extraction | Auto (regex) | No | No | Yes (LLM) | Yes (LLM) | | Memory consolidation | Yes | No | No | Yes (LLM) | No |

Tested

• 206 unit tests covering core CRUD, namespaces, temporal versioning, entity extraction, consolidation, WAL management, HTTP server, error handling
• 107 quality tests against real-world agent memory data (100 search queries across 10 categories, all passing)
• Benchmark suite with reproducible numbers: <1ms hybrid query, 10K+ inserts/sec, ~835 bytes/memory
• Auto-translate for multilingual queries (Russian → English via deep-translator: 4/10 → 10/10)
• Python 3.10, 3.11, 3.12

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: oxgeneral
• Source: oxgeneral/agentmem
• License: MIT

Install and usage instructions live in the source repository linked above.