VeraMem
Long-term memory for AI agents that you can verify, that uses task outcomes to rank memories, and that is safe to share.
- One SQLite file, no servers to run.
- Works fully offline with Ollama, or with OpenAI / Anthropic.
- Python SDK, REST API with a web UI, and an MCP server for Claude Desktop, Cursor and Claude Code.
pip install "veramem[mcp]"
veramem init # finds Ollama / OpenAI / Anthropic and sets everything up
veramem add "I'm vegetarian and I moved to Lisbon last week"
veramem ask "where do I live?"
veramem serve # web UI on http://127.0.0.1:8765
from veramem import Memory
mem = Memory() # auto-detects your model provider
mem.add("I moved to Lisbon last week", user_id="priya")
mem.answer("Where does Priya live?", user_id="priya")
# Answer(answer='Lisbon', citations=['mem_…'], abstained=False, trace_id='tr_…')
Why another memory system?
Today's memory layers (Mem0, Letta, Graphiti/Zep, MemOS, TencentDB-Agent-Memory) have three gaps. VeraMem fills each one with techniques from recent research:
| The gap | What VeraMem does | |
|---|---|---|
| A | Memories are kept or dropped by heuristics. Whether a memory actually helped is never recorded. | Outcome-informed ranking: feedback(trace_id, reward, cited=...) records which memories an agent used and how it went. Query-aware utility re-ranks similar future searches. A learned ranker, deployed only when it beats retrieval with 95% confidence, learns non-retrieval signals such as source authority from feedback and transfers them to unseen tasks (Hit@1 0.14 → 1.00 on held-out attributes). On LoCoMo, a tuned static weighting beats it (+3.4 vs +2.1 pts). Write decisions are prompted, not learned. Evidence and negative results. (Memory-R1, AgeMem) |
| B | Extracted "facts" lose the link to what was said. A tool's claim quietly becomes "the user's preference". | Every memory points to a verbatim, verified quote in an immutable, hashed source message. Each carries a source-authority label (user / assistant / tool) that consolidation can never raise. Updates are versioned and time-travel queryable. Every write goes into a hash-chained ledger. Answers cite or abstain, and check_action() blocks low-authority memories from driving payments, bookings or sends. (Agent Zero Memory, AMA, AuthMem-Bench) |
| C | Sharing is all-or-nothing. Private data leaks through shared pools, dedup, or other users' preferences. | Access rules are compiled into SQL before ranking. Revocable user↔agent and agent↔resource grants apply retroactively. Preferences can never be shared. Experiences are shared through a two-stage pipeline with de-identification plus a deterministic PII/canary gate. Erasure is physical. (ShareMem, Collaborative Memory, AIM) |
The paper-by-paper mapping is in docs/RESEARCH.md, and the design is in docs/ARCHITECTURE.md.
Benchmarks
Measured head-to-head on the same machine, with the same local model (qwen3.6:35b,
thinking off, temperature 0) and the same embedder (nomic-embed-text) for every system.
The full method and raw outputs are in docs/BENCHMARKS.md.
Head-to-head with mem0 2.2.1 (its best OSS setup), both on the same local model.
Raw results: docs/results/.
| What is measured | VeraMem | mem0 |
|---|---|---|
| Cross-user leakage over 336 adversarial queries | 0% | 0% |
| Tool, document or assistant claims stored as the user's own (all 7 AuthMem-Bench transitions) | 0.0% | 2.9% |
| Those claims still retained, with attribution (Ret⁻) / user statements retained (Ret⁺) | 100% / 94% | 97% / 89% |
| Machine-checkable authority to block risky actions | yes | no |
| Current value ranked first after three changes | 75% | 50% |
| Wrong top answer fixed by feedback within 5 rounds (synthetic) | 0% → 100% | no feedback API |
| Feedback improves retrieval on unseen task families (LoCoMo, 5 seeds, placebo-controlled) | +2.1 pts Hit@3 [+1.1, +3.1]; a tuned static weighting gets +3.4 without feedback | no feedback API |
| Feedback teaches source authority on unseen attributes (synthetic, 5 seeds) | Hit@1 0.14 → 1.00 | no feedback API |
| Revoking an agent's access hides its memories | yes | not supported |
| Tampering with stored memories detected | yes | not supported |
| User's secret left in plaintext on disk after deleting the user | no | yes (history.db) |
| Search latency p50 | 4 ms | 40 ms |
Status: these are the guarantee tests in
benchmarks/guarantees.py, which follow the protocols of the cited papers on synthetic data. Accuracy on the standard LoCoMo and LongMemEval benchmarks is being measured and will be published here, wins or losses included.
Reproduce:
python -m benchmarks.guarantees --systems veramem,mem0
python -m benchmarks.locomo --systems veramem,mem0 --convs all
What you get
| Feature | API | CLI |
|---|---|---|
| Remember chats, tool results, documents (role sets authority) | add(messages, user_id=…) |
veramem add |
| Hybrid search (dense + BM25 + entity, routed by granularity) | search(q, user_id=…) |
veramem search |
| Grounded answers with citations and abstention | answer(q, user_id=…) |
veramem ask |
| Outcome-informed ranking | feedback(trace_id, reward, cited=…), train_ranker(), learn(task, trajectory, reward) |
veramem feedback, veramem train-ranker |
| Evidence and version history | evidence(id), history(id), search(…, as_of=ts) |
veramem history |
| Authority gate for actions | check_action([ids]) |
|
| Teams, grants, revocation | join_team, grant_agent, revoke_agent, grant_resource |
|
| Safe sharing | set_shareable, share(user_id, team_id) |
|
| Tamper check | verify() |
veramem verify |
| Right to be forgotten / data export | forget(user_id=…, everything=True), export(user_id) |
veramem forget, veramem export |
| Training data for your own memory model | export_trajectories(path) |
veramem export-trajectories |
| Maintenance (archive, dedupe, summarise) | consolidate() |
veramem consolidate |
Use it from any app
-
Python SDK:
MemoryandAsyncMemory. -
TypeScript SDK:
sdk/typescript, with no runtime dependencies; works in Node 18+ and browsers. -
Agent frameworks: LangChain, LangGraph (long-term
BaseStore), LlamaIndex and CrewAI adapters, plus plain tool schemas for OpenAI and Anthropic tool calling. See docs/guide/frameworks.md. -
MCP (Claude Desktop, Claude Code, Cursor, VS Code):
veramem mcp-configprints the config to paste. See examples/mcp_clients.md. -
REST:
veramem serveserves interactive docs at/docs. SetVERAMEM_API_KEYto require a bearer token; the CLI refuses to listen publicly without one. -
Docker:
VERAMEM_API_KEY=… docker compose upstarts VeraMem plus Ollama, fully local. -
Multi-user deployments: per-user API keys or OIDC/JWT, PostgreSQL for many replicas, rate limits, and a web UI for sharing, access and key management. See docs/guide/deployment.md.
Configuration
veramem init writes ~/.veramem/config.json. You can override any setting with an
environment variable:
| Variable | Meaning |
|---|---|
VERAMEM_LLM |
ollama · openai · anthropic · none |
VERAMEM_LLM_MODEL, VERAMEM_LLM_BASE_URL |
e.g. qwen3:8b, or any OpenAI-compatible URL (vLLM, LM Studio, Groq, Together) |
VERAMEM_EMBEDDER, VERAMEM_EMBED_MODEL |
ollama · openai · hash (no model at all) |
VERAMEM_DB |
Path of the SQLite file |
VERAMEM_API_KEY |
Bearer token for the REST API |
With no model at all, VeraMem still works. It stores and searches raw messages, with the same access control and ledger.
Security and trust
- No telemetry, ever. The only network calls go to the model provider you configure.
- Releases are built in CI with SLSA provenance, signed with Sigstore, and published to PyPI with OIDC trusted publishing.
- Contributions follow a vouched-contributor model: open an issue first. See CONTRIBUTING.md, SECURITY.md and GOVERNANCE.md.
License
Apache-2.0. Some prompts are adapted from mem0 and AMA (both Apache-2.0); see NOTICE.
1 maintainer
Metadata
1 maintainer
Release files for veramem 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| veramem-0.1.0.tar.gz | 139.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| veramem-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 269.2 kB
Release files / veramem-0.1.0.tar.gz
| Download URL | veramem-0.1.0.tar.gz |
|---|---|
| Size | 139.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
364f1560288298e208b8d3692ded780770394555d1253d5e94b0d0d7ad07bbdb
|
|
BLAKE2b-256 checksum How to use checksums |
422bd9be51fb4299e5487a938601a309946166d64112445cfa3e762a86091c48
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Release files / veramem-0.1.0-py3-none-any.whl
| Download URL | veramem-0.1.0-py3-none-any.whl |
|---|---|
| Size | 130.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31ebf5e1e76c855dfee32e6d1a67b718e26b803dd9d14d7d1a6c96944a0a4a60
|
|
BLAKE2b-256 checksum How to use checksums |
9817e83236fc051bb220757c288b28d6b0beda562571152bf2d8bbe8e5ee24f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.15
|
Security for veramem 0.1.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.
