VoltMem

Current-truth memory for LLM agents.

Most memory layers treat every fact the same — your hometown and today's mood get equal weight. That forces a bad tradeoff: go stale on fast-changing facts, or get corrupted when a confident-but-wrong update overwrites something durable.

VoltMem scales protection and retrieval freshness by how fast each kind of fact actually changes. Volatile facts update; stable facts resist corruption; stale volatile memories rank lower at search time.

Mem0 remembers relevant facts. VoltMem remembers current truth.

Research & benchmarks: docs/RESEARCH.md · Known limits & roadmap: docs/OPEN_PROBLEMS.md · Sleeptime roadmap: docs/SCHEDULE.md · Control-law spec (Lean): lean/README.md · Related FEP research (sibling): docs/RELATED.md

What’s new in 0.5.0

• Domain-scoped clear — Memory.clear(domain="…") and DELETE /v1/tenants/{id}/memories?domain=… remove one kind without wiping the tenant; omit domain for a full clear
• Memory browser — graph zoom/pan, tooltips, collision layout, list pagination, Clear tenant / Clear domain with typed confirm

What’s new in 0.4.0

• Composite default — escalation_mode="composite" (homeostatic insurance on weak evidence; allostatic on explicit high-M or unexpected residual). "homeostatic" / "current" remain available
• Heuristic write matching — persist (subject, attribute, value); match by subject, not cosine. Grey frames insert as twins. False merge = 0 preferred over extra link accuracy
• Sleeptime 14B — with embeddings, a local verifier is attached for reconcile_twins (sidecar daemon; VOLTMEM_RECONCILE_TWINS / VOLTMEM_RECONCILE_INTERVAL). Live add() / remember() stay millisecond. Hatch: verify_on_write=True or sidecar VOLTMEM_VERIFY_ON_WRITE=1
• Shipped claim is embeddings + sidecar sleeptime. Keyword-only still uses the threshold ladder (false merges). Twins coexist until reconcile_twins runs

What’s new in 0.3.1

• Real consolidate — mismatch evidence log + heuristic/LLM summarizer; scheduled in the sidecar (VOLTMEM_CONSOLIDATE / VOLTMEM_CONSOLIDATE_INTERVAL); skips when no evidence
• Vector index event_id — stored on upsert; optional search filter; legacy DB migration
• Evals — multi-facet linked retrieve + independent stale@k/audit (tests/test_multi_facet_eval.py); TTL haystack 0% past expiry (tests/test_ttl_haystack_eval.py)

What’s new in 0.3.0

• Multi-facet events — event_id / modality on items; add_event() + retrieve_by_event() (Python, sidecar, TypeScript client)
• Optional TTL — expires_at / ttl_seconds; retrieval skips expired rows; expire_cleanup purges them (ledgered, index-synced)
• Maintenance substrate — MaintenanceWindow, flag tasks (pattern_audit, reclassify_ambiguous), run ledger + rollback_maintenance(run_id)
• Sidecar sleeptime hooks — POST .../maintenance/trigger + .../rollback; background daemon runs due expire/audit/consolidate tasks (VOLTMEM_MAINTENANCE=1); consolidate merges mismatch evidence into updated tips (skip if no evidence; disable with VOLTMEM_CONSOLIDATE=0)
• Classification eval corpus — 230 labeled utterances / 14 domains; heuristic baseline ≈84%; CI floors in tests/test_classifiers.py
• SQLite WAL — file-backed DBs open in WAL mode for HTTP + maintenance concurrency

What’s new in 0.2.2

• Adaptive freshness mix — when top candidates have nearly equal similarity (under-specified queries), VoltMem dampens the volatility penalty so freshness cannot dominate near-ties; clear similarity gaps keep full freshness behavior
• domain_stats() — always-on prior calibration telemetry (insert / confirm / mismatch / audit counts and rates per domain); does not require auto_discover
• Calibration histogram — experiments/prior_calibration_hist.py (ASCII + SVG)

Install

pip install voltmem[embeddings]
# from source:
# pip install -e ".[embeddings]"

Core library has zero required dependencies. Embeddings extras pull in sentence-transformers (recommended). LangChain: pip install -e ".[langchain]". HTTP sidecar (FastAPI): pip install -e ".[sidecar]" — see sidecar/README.md.

Quickstart

from voltmem import create_memory

mem = create_memory("app.db", user_id="alice")

mem.add("I live in Berlin")
mem.add("I prefer concise, direct answers")
mem.add("Actually I moved to Paris last month")   # updates location, not prefs

hits = mem.search("where does the user live?", limit=3)
print(hits[0]["memory"])   # Actually I moved to Paris last month

Message pairs (auto fact extraction)

mem.add([
    {"role": "user", "content": "I moved to Paris. I'm working on a DB migration."},
], extract=True)   # default for message lists — splits into atomic facts

Optional: create_memory(..., llm_extract=True) for Ollama-powered extraction.

Inject into a prompt

memories = mem.search(user_message, limit=5)
context = "\n".join(f"- {m['memory']}" for m in memories)
system = f"What you know about this user:\n{context}"

API

Advanced: mem.layer exposes MemoryLayer for low-level observe() / write().

create_memory(..., vector_index="auto") enables a SQLite embedding index when an embedder is present ("off" restores full-scan retrieval). VoltMem always applies volatility re-ranking on top of vector candidates — not raw ANN results.

With embeddings on (the create_memory default), a local verifier is attached for sleeptime reconcile_twins. Live remember() / add() use millisecond heuristic cards and insert grey frames as twins. Pass verify_on_write=True to ask the verifier on write. Keyword-only layers (embeddings=False, or MemoryLayer() with no embedder) keep the threshold ladder. Pass link_verifier=None to force the ladder even with embeddings.

stats = mem.domain_stats()
# {
#   "location": {"prior": 0.6, "audited": 4, "logged_mismatch": 2,
#                "confirmed": 10, "audit_rate": 0.25, ...},
# }

flowchart LR
  Q[search query] --> E[embed query]
  E --> V[vector index: top candidates]
  V --> S[SQLite: load memory records]
  S --> P{sim spread flat?}
  P -->|no| R[full freshness re-rank]
  P -->|yes| D[dampen freshness mix]
  R --> T[current truth]
  D --> T

Why VoltMem

Example results (reproducible)

Run locally with pip install -e ".[embeddings]". Embeddings: sentence-transformers (all-MiniLM-L6-v2).

examples/contradiction_demo.py — 5-turn script vs naive always-add:

experiments/mem0_comparison.py — 3 scenarios, top-1 search (always-add baseline):

VoltMem clearer wins: 2/3 (always-add also finds Paris on location, but keeps stale facts).

experiments/mem0_side_by_side.py — same 3 scenarios vs real Mem0 (open-source, gpt-4o-mini + text-embedding-3-small):

VoltMem clearer wins: 3/3. Mem0 keeps contradictory facts; VoltMem updates volatile slots and protects stable prefs via domain volatility + slot-aware linking.

experiments/voltmem_eval.py — end-to-end escalation + retrieval (real vs flat vs swap):

Includes the professional_context career-change probe (strong explicit evidence → update).

experiments/memory_demo.py — 3 final Q&A checks vs ground truth:

VoltMem is the only policy that both rejects confident false blips on stable facts and tracks weak-but-true updates on volatile ones. Full distributions: docs/RESEARCH.md (llm_memory_bench.py).

python examples/contradiction_demo.py
python experiments/mem0_comparison.py
python experiments/mem0_side_by_side.py   # pip install mem0ai; OPENAI_API_KEY or MEM0_BACKEND=ollama
python experiments/voltmem_eval.py        # 20/20 escalation probes + retrieval separation
python experiments/memory_demo.py

Integrations

LangChain

pip install -e ".[langchain]"
python examples/langchain_agent.py

from voltmem.integrations.langchain import VoltMemMemory

memory = VoltMemMemory(session_id="user-42", db_path="app.db")
memory.load_memory_variables({"input": "Where do I live?"})
memory.save_context({"input": "I moved to Paris"}, {"output": "Noted."})

Multi-tenant

One SQLite file, many tenants. user_id is the tenant id — a person (alice) or an app bucket (relay-local) — and is stored as the namespace column:

alice = create_memory("app.db", user_id="alice")
bob   = create_memory("app.db", user_id="bob")

The HTTP sidecar uses the same id on /v1/tenants/{tenant_id} (/v1/users/{tenant_id} remains as a deprecated alias). Glossary: docs/SIDECAR.md.

HTTP sidecar / TypeScript

For Cloudflare Workers and other TypeScript apps, run VoltMem as an HTTP sidecar instead of porting the engine. The Worker stays thin and calls REST (add / search / domain_stats).

Consumer deploy guide: docs/SIDECAR.md — Docker pull/build, production checklist, Fly.io, connecting @voltmem/client.

# Anyone can build the public Dockerfile
git clone https://github.com/Rouche01/voltmem.git && cd voltmem
docker build -t voltmem-sidecar .
docker run -p 8080:8080 -e VOLTMEM_API_KEY=secret -v voltmem-data:/data voltmem-sidecar

# Or run without Docker
pip install -e ".[sidecar,embeddings]"
VOLTMEM_API_KEY=secret VOLTMEM_DB_PATH=./voltmem_sidecar.db python -m sidecar

API reference: sidecar/README.md · TypeScript SDK: clients/typescript.

Examples

Chat app (CLI)

pip install -e ".[embeddings]"
python -m examples.chat_app              # REPL; uses Ollama if running, else echo mode
python -m examples.chat_app --demo       # scripted smoke test
python -m examples.chat_app --show-recall

Slash commands: /memories, /search <query>, /clear, /reset, /help.

Domain volatility priors

Custom domains: register via DomainRegistry and pass to create_memory(domains=...). Pluggable classifiers: create_memory(classifier=...) — "heuristic", "llm", KeywordClassifier, or a callable dict.

mem.domain_stats() always records insert / confirm / mismatch / audit rates per domain (prior calibration). Optional: create_memory(..., auto_discover=True) also blends empirical volatility into scoring from those patterns (cold-start applies).

from voltmem import create_memory, DomainRegistry, KeywordClassifier, ChainedClassifier, HeuristicClassifier

domains = DomainRegistry()
domains.register("style_preference", 0.08)
domains.register("style_constraint", 0.25)

mem = create_memory(
    "app.db",
    user_id="alice",
    domains=domains,
    classifier=ChainedClassifier([
        KeywordClassifier({
            "style_preference": ["prefer", "darker colors", "minimal"],
            "style_constraint": ["no wool", "tight budget"],
        }),
        HeuristicClassifier(),
    ]),
)

mem.add("I prefer darker colors and minimal fits")
hits = mem.search("what colors does the user like?")

Development

pip install -e ".[all]"
python tests/test_voltmem.py
python tests/test_multi_facet_eval.py
python tests/test_ttl_haystack_eval.py
python tests/test_client.py

Experiments and benchmarks live in experiments/ — see docs/RESEARCH.md. Open problems and roadmap: docs/OPEN_PROBLEMS.md.

python experiments/prior_calibration_hist.py   # ASCII + experiments/out/*.svg
python experiments/retrieval_plateau_probe.py

License

MIT