agentrecall-db

agentrecall

Agent memory in a single SQLite file. No vector database, no server, no cloud, no API key.

pip install agentrecall-db

Installs as agentrecall-db on PyPI (the bare agentrecall name was taken). You still import agentrecall and run the agentrecall CLI — only the install name differs.

from agentrecall import Memory

with Memory("agent.db") as mem:                      # one SQLite file, nothing else running
    mem.add("The user prefers dark mode", tags=["preference"])
    mem.add("User's name is Aziz; lives in Tashkent", metadata={"kind": "fact"})

    # The core install gives you fast keyword recall (SQLite FTS5). For meaning-based
    # search that matches paraphrases, add the [semantic] extra — see below.
    for hit in mem.search("dark mode preference", k=3):
        print(hit.score, hit.content)

That's the whole setup. agent.db is an ordinary SQLite file you can cp, git diff, back up, inspect with any SQLite tool, and read from any language. Nothing else is running.

---

Why another memory library?

Most "memory layers" for agents are infrastructure. To get started you stand up a vector database, run a server, sign up for a cloud, or hand over an API key — and many of them call an LLM on every write to "extract" facts, which is slow, costs tokens, and is non-deterministic.

agentrecall is the opposite. It is a library, the store is one file, recall is deterministic, and nothing leaves the machine.

Three things agentrecall does that nothing else combines:

1. Zero infrastructure. The core has no third-party dependencies — keyword recall runs on Python's stdlib sqlite3 (FTS5 + BM25). A fresh pip install agentrecall-db with nothing else works.
2. Semantic search with no torch, no GPU, no download server. Add the [semantic] extra and you get hybrid keyword + vector recall powered by model2vec static embeddings (~10 MB, CPU-only) stored in sqlite-vec. Still one file, still offline.
3. Verbatim & deterministic. agentrecall never calls an LLM to mutate your memories. What you add() is what is stored — no silent fact-extraction, no cloud round-trip, no surprise token bills.

---

Install

pip install agentrecall-db                 # core: keyword recall, stdlib only
pip install "agentrecall-db[semantic]"     # + torch-free semantic search (model2vec + sqlite-vec)
pip install "agentrecall-db[mcp]"          # + MCP server
pip install "agentrecall-db[all]"          # everything

Semantic search (optional, torch-free)

from agentrecall import Memory

# embeddings="auto" (the default) turns semantic on automatically *iff* the
# [semantic] extra is installed, and silently stays keyword-only otherwise.
mem = Memory("agent.db", embeddings="auto")
print(mem.semantic_enabled)   # True once you've installed agentrecall[semantic]

mem.add("I love hiking in the mountains on weekends")
hits = mem.search("outdoor hobbies")     # matches even with zero shared keywords

Search is hybrid: keyword (FTS5/BM25) and vector (cosine) candidates are blended with Reciprocal Rank Fusion, so you get the precision of keywords and the recall of embeddings. Bring your own embedder (OpenAI, a local model, anything) by passing embedder= — any object with .dim and .embed(texts) -> list[list[float]].

Optional ranking boosts:

mem = Memory("agent.db", recency_weight=0.5, importance_weight=0.3)
mem.add("Critical: API key rotates on the 1st", importance=3.0)
mem.search("api key", recency_weight=1.0)   # per-call override

Expiring memories (TTL)

Not every fact is true forever. A memory added with a ttl stops being recalled once its deadline passes — no cron job, no cleanup pass, no if in your agent loop:

mem.add("User is debugging the staging deploy", ttl="4h")   # gone after the session
mem.add("Rate limit resets at 14:00 UTC", ttl="1h")
mem.add("User's name is Aziz", )                            # no ttl → permanent

ttl accepts "30d", "12h", "1h30m", a number of seconds, or a timedelta. For an absolute deadline, pass expires_at=<datetime> instead (the two are mutually exclusive).

Expiry is a visibility rule, applied in SQL before the LIMIT, so an expired memory never occupies a slot in your top-k:

mem.search("staging")          # expired memories are absent
mem.all()                      # absent
mem.get(memory_id)             # raises MemoryNotFound
mem.count()                    # doesn't count them

mem.search("staging", include_expired=True)   # opt back in, on any read

Nothing is deleted until you say so. Rows linger — invisible — until you reclaim the disk:

mem.purge_expired()            # returns how many rows went

Because it only removes what's already invisible, running it (or never running it) cannot change what your agent recalls. To renew or cancel a deadline:

mem.update(mid, ttl="7d")          # restart the countdown from now
mem.update(mid, expires_at=None)   # drop the deadline — permanent again

update() finds already-expired memories, so a renewal brings one back.

Namespaces

Isolate memories per user, per agent, or per session with a namespace:

alice = Memory("app.db", namespace="user:alice")
bob   = Memory("app.db", namespace="user:bob")     # same file, isolated memories
alice.add("prefers metric units")
bob.search("units")          # never sees Alice's memories

As an MCP server

Give Claude (or any MCP client) persistent, searchable memory — an embeddings-capable alternative to the official keyword-only JSONL memory server:

pip install "agentrecall-db[mcp]"
agentrecall serve --db ~/.agent-memory.db

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "memory": {
      "command": "agentrecall",
      "args": ["serve", "--db", "/Users/me/.agent-memory.db"]
    }
  }
}

Tools exposed: remember, recall, forget, forget_expired, list_memories, memory_stats. remember takes an optional ttl, so the model can mark a fact as session-scoped when it stores it.

CLI

agentrecall add "Deadline is July 7" --tags project --importance 2
agentrecall add "Debugging staging today" --ttl 4h    # expires on its own
agentrecall search "when is the deadline" -k 3
agentrecall list --limit 10 --include-expired
agentrecall stats                                     # live count + how many expired
agentrecall forget --keep-last 1000        # prune to the newest 1000 per namespace
agentrecall forget --expired               # reclaim disk from elapsed TTLs
agentrecall export --format md > memories.md

Move a store between machines with the JSON round-trip (- reads stdin):

agentrecall --db old.db export > memories.json
agentrecall --db new.db import memories.json

Import accepts either a JSON array or one object per line (JSONL), and preserves tags, metadata, importance, namespace, and expiry. Ids are reassigned by the destination.

Every command honours --db, --namespace, and the AGENTRECALL_DB / AGENTRECALL_NAMESPACE / AGENTRECALL_EMBEDDINGS environment variables.

API at a glance

mem.add(content, *, tags=None, metadata=None, importance=1.0, namespace=None,
        ttl=None, expires_at=None)                                           -> MemoryRecord
mem.add_many([str | dict, ...])                                              -> list[MemoryRecord]
mem.search(query, *, k=5, namespace=None, tags=None, recency_weight=None,
           importance_weight=None, include_expired=False)                    -> list[MemoryHit]
mem.get(id, *, include_expired=False) / mem.update(id, ...) / mem.delete(id)
mem.all(*, namespace=None, tags=None, limit=None, offset=0,
        include_expired=False)                                               -> list[MemoryRecord]
mem.count(*, namespace=None, include_expired=False) -> int
mem.forget(*, before=None, namespace=None, keep_last=None) -> int           # deleted count
mem.purge_expired(*, namespace=None) -> int                                 # deleted count

tags filtering matches memories containing all of the requested tags.

The database is just SQLite

No magic. Open it with anything:

sqlite3 agent.db "SELECT id, content, importance, created_at FROM memories ORDER BY created_at DESC LIMIT 5;"

Schema: a memories table (with JSON tags/metadata columns and a nullable expires_at), an FTS5 index kept in sync by triggers, and — only in semantic mode — a sqlite-vec vector table. See SPEC.md for the full contract.

Older database files are migrated in place on open: the expires_at column is added and existing rows keep NULL, i.e. they never expire.

Scope & limits (honest defaults)

• Agent-scale, not web-scale. sqlite-vec uses a linear scan (no ANN index yet) — great for thousands of memories per namespace, not millions of RAG chunks.
• Sync, single-process. Use one Memory per thread. sqlite3 is fast and local; there is no async API by design.
• No knowledge graph / entity-relation modeling. That's Cognee and Zep's lane. agentrecall stays small on purpose.
• No automatic summarization. Memories are stored verbatim. If you want LLM-distilled memories, distill before you add() — your call, your model, your tokens.
• add() is append-only. Re-adding the same text creates a new row (no content dedupe). To revise a memory, keep the integer id returned by add() and call update(id, ...) / delete(id).
• forget(before=..., keep_last=...) deletes the union — rows older than before or beyond the newest keep_last per namespace. With neither argument it's a no-op (to wipe a store, just delete the file).
• TTL hides, it doesn't delete. An expired memory stays on disk until purge_expired(). That's deliberate — expiry is reversible (update(id, ttl=...)), and a SELECT in sqlite3 still shows you what an agent has stopped recalling.

Development

pip install -e ".[dev]"
pytest
ruff check .

The keyword (FTS-only) test suite runs with zero third-party dependencies. Semantic tests are skipped automatically when the [semantic] extra isn't installed.

License

MIT © 2026 Shaxzodbek Qambaraliyev / Blaze