Skip to main content

remembrane

Local-first persistent memory for AI agents. One SQLite file, zero required dependencies. Exact hybrid recall (vector + BM25 — never approximate), explainable ranking, time-travel over memory history, and deterministic behavior you can unit-test in CI. Adapters for LangChain and CrewAI, plus a built-in MCP server.

pip install remembrane

Why

Agents forget everything between sessions. Existing memory solutions are cloud APIs, require a vector database, or drag in a heavyweight framework. remembrane is the opposite:

  • One file. Your agent's entire memory is a SQLite database you can copy, back up, diff, or delete.
  • Zero required dependencies. The default embedder is pure stdlib. pip install remembrane pulls in nothing else.
  • Human-like recall. Results are ranked by a composite of similarity, recency decay (memories halve in weight every week by default), and importance. Recalled memories are reinforced — spaced repetition for agents.
  • Exact, not approximate. Large systems use approximate nearest-neighbor search and accept missed results. At agent-memory scale, remembrane scores every memory — hybrid vector + BM25 keyword in one pass, guaranteed complete.
  • A memory you can debug. Every store/forget/reinforce is journaled. Snapshot, diff, and reconstruct what your agent knew at any point in time. Every recall result explains exactly why it ranked where it did.
  • Testable in CI. Deterministic embedder + frozen-time recall = reproducible memory behavior. remembrane.testing ships pytest-friendly assertions.
  • Framework-agnostic. Use it bare, through the LangChain or CrewAI adapters, or expose it to any MCP-capable agent (like Claude) as an MCP server.

Quick start

from remembrane import MemoryStore

mem = MemoryStore("agent.db")            # or ":memory:" for ephemeral

mem.store("User prefers dark mode", importance=0.8)
mem.store("Deploy target is AWS us-east-1", namespace="ops")

results = mem.recall("what theme does the user like?")
print(results[0].memory.content)         # → "User prefers dark mode"
print(results[0].score)                  # similarity × recency × importance

Memory lifecycle

mem.reinforce(memory_id)                  # strengthen: slower decay, higher rank
mem.forget(memory_id)                     # delete one
mem.forget(namespace="ops")               # delete a namespace
mem.forget(older_than_seconds=30*86400)   # prune stale memories
mem.consolidate()                         # merge near-duplicates
mem.export()                              # plain dicts, ready for json.dump

Tuning recall

from remembrane import MemoryStore, ScoringConfig

mem = MemoryStore(
    "agent.db",
    scoring=ScoringConfig(
        weight_similarity=0.7,
        weight_recency=0.15,
        weight_importance=0.15,
        half_life_seconds=7 * 24 * 3600,   # recency halves every week
    ),
)

Embedders

The default HashEmbedder is deterministic, offline, and dependency-free — it hashes word and character n-grams. That makes similarity lexical, not semantic. It works well for typical agent memories (facts, preferences, short statements). For true semantic recall, plug in a real model:

from remembrane import MemoryStore, SentenceTransformerEmbedder, OpenAIEmbedder

mem = MemoryStore("agent.db", embedder=SentenceTransformerEmbedder())   # local, pip install remembrane[sentence-transformers]
mem = MemoryStore("agent.db", embedder=OpenAIEmbedder())                # API,   pip install remembrane[openai]

Any object with embed(texts) -> List[List[float]] and a dimension attribute works.

Note: don't mix embedders in one database. Vectors from different embedders aren't comparable.

LangChain

from remembrane import MemoryStore
from remembrane.adapters import RemembraneChatMemory

memory = RemembraneChatMemory(MemoryStore("agent.db"), session_id="user-42")

memory.save_context({"input": "my favorite color is teal"}, {"output": "Noted!"})
memory.load_memory_variables({"input": "what color do I like?"})
# {'history': 'human: my favorite color is teal\nai: Noted!'}

Unlike buffer memory, this retrieves the exchanges relevant to the current input — the context window stays small no matter how long the history grows.

CrewAI

from remembrane import MemoryStore
from remembrane.adapters import RemembraneStorage

storage = RemembraneStorage(MemoryStore("crew.db"))
storage.save("the deadline is next friday", metadata={"task": "planning"})
storage.search("when is the deadline?")

MCP server

Give any MCP-capable agent (e.g. Claude Desktop, Claude Code) persistent memory:

pip install remembrane[mcp]
remembrane-mcp --db ~/agent-memory.db
{
  "mcpServers": {
    "remembrane": {
      "command": "remembrane-mcp",
      "args": ["--db", "/path/to/agent-memory.db"]
    }
  }
}

Tools exposed: memory_store, memory_recall, memory_forget, memory_reinforce, memory_stats.

CLI

remembrane --db agent.db store "the user prefers dark mode" --importance 0.8
remembrane --db agent.db recall "what theme?"
remembrane --db agent.db list
remembrane --db agent.db stats
remembrane --db agent.db export > backup.json

Time travel

Every mutation is journaled, so the past is queryable:

mem.snapshot("before-research")
# ... agent runs, learns things, forgets things ...

mem.diff("before-research")
# {'added': [{'content': 'competitor launched a new pricing tier', ...}],
#  'removed': [...], 'changed': [...]}

mem.as_of("before-research")          # full memory state at that point
mem.log()                             # newest-first history of every operation

Or from the CLI: remembrane snapshot v1, remembrane diff v1, remembrane log. "What did my agent believe last Tuesday, and what changed its mind?" is now an answerable question.

Explainable recall

No black boxes — every result carries its full ranking breakdown:

r = mem.recall("what theme does the user like?")[0]
r.explain()
# {'score': 0.6087, 'components': {'vector_similarity': 0.71, 'keyword_bm25': 1.0,
#   'combined_similarity': 0.81, 'recency': 0.98, 'importance': 0.8}, ...}
r.explain_text()
# 'score 0.609 = similarity 0.812 (vector 0.713, keyword 1.000) + recency 0.984 + importance 0.80 | recalled 3x'

Testing your agent's memory

Deterministic recall means memory behavior is unit-testable — something no cloud memory API can offer:

from remembrane.testing import assert_recalls, assert_recalls_first, assert_not_recalls

def test_agent_remembers_allergies():
    mem = build_agent_memory()
    assert_recalls_first(mem, "any food allergies?", "peanuts")
    assert_not_recalls(mem, "any food allergies?", "dark mode", k=1)

Pass now=... to recall() to freeze time and make recency scoring reproducible.

Merging memories

Memory files are portable — merge two agents' brains, with near-duplicate absorption:

mem.merge_from("other-agent.db")            # {'added': 12, 'merged': 3}
mem.merge_from("backup.db", namespaces=["prefs"], dedupe_threshold=0.95)

CLI: remembrane --db a.db merge b.db

How ranking works

score = 0.7·similarity + 0.15·recency + 0.15·importance
recency = exp(−ln2 · age / half_life)

age is measured from the memory's last access, not creation — every recall resets the decay clock. Frequently-used memories stay vivid; untouched ones fade. In the default hybrid mode, similarity is 0.65·cosine + 0.35·bm25. All weights, the mode, and the half-life are configurable.

Design choices

  • SQLite over a vector DB — agent memory stores are small (thousands, not billions, of rows). Brute-force cosine over a few thousand vectors is sub-millisecond, and you gain transactions, a single portable file, and zero infra.
  • No background daemon — decay is computed at read time, so nothing runs when your agent doesn't.
  • Duck-typed adapters — remembrane never imports langchain or crewai; the adapters match their interfaces structurally, so there are no version-pinning fights.

Development

git clone https://github.com/satyasairay/remembrane
cd remembrane
pip install -e .[dev]
pytest

License

MIT

Metadata

Release files for remembrane 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for remembrane 0.2.0
File Size Uploaded Provenance Actions
remembrane-0.2.0.tar.gz 24.5 kB Without provenance Details for remembrane-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for remembrane 0.2.0
File Interpreter ABI Platform Actions
remembrane-0.2.0-py3-none-any.whl Python 3 none any Details for remembrane-0.2.0-py3-none-any.whl

Total release size: 48.9 kB

Release files / remembrane-0.2.0.tar.gz

Download URL remembrane-0.2.0.tar.gz
Size 24.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8227c869669a3d1c77559473105f07497ba70611c120361c5b270e11c54b58de
BLAKE2b-256 checksum
How to use checksums
254af90d97bb05873d7a671a6191bfe228502a7416143751d1d1d81ba78b44d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Release files / remembrane-0.2.0-py3-none-any.whl

Download URL remembrane-0.2.0-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df15b92697188977ea3f2fe1b9a9d450953ef25ca61cfe2ffc65cb30aba4ac4a
BLAKE2b-256 checksum
How to use checksums
7cdf8a5130cc832760b3a1d7e1a8eb652f1201af9258a7f8539641e7fa2978cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.3

Security for remembrane 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page