Verimem

Verified memory for AI agents. Every write passes an admission gate, every read carries provenance, and when the evidence isn't there the system abstains instead of guessing.

Most memory layers optimize for how much they can recall. Verimem optimizes for whether you can trust what comes back: facts are admitted through an anti-confabulation gate, stored with their sources, revised through explicit supersession (never silent overwrites), and answered with citations — or with an honest "I don't know."

Features

• Gated writes — every fact enters as a low-trust claim and must be backed by evidence to gain status. Unsupported or contradictory assertions are flagged instead of absorbed (anti-sycophancy on the write path).
• Provenance on every read — answers cite where each fact came from (conversation, document offset, tool call). A TrustReport explains how the system knows: chain of custody, declared conflicts, or an explicit abstention.
• Bi-temporal history — facts carry both when it happened and when we learned it. Query the past (as_of), see transitions ("changed from X to Y on date Z"), and audit every revision.
• Abstention by design — on questions the store cannot support, Verimem says so. Memory-boundary abstention holds at 1.0 across our end-to-end runs.
• Document memory with exact citations — index PDF/DOCX/HTML/text files; semantic search returns passages with file, version and character offsets; passages can be promoted to memory through the gate, citation attached.
• Consent-first import — bootstrap from your ChatGPT / Claude export: conversations are listed first, nothing is ingested without an explicit selection.
• True forget — delete(purge_history=True) removes the fact and its supersession chain; the deleted data does not resurface through history or time-travel queries.
• Local-first — SQLite storage, local embeddings, injectable LLM. Runs air-gapped (verimem airgap verifies zero-egress configuration).

Install

pip install verimem

Quickstart (Python)

from datetime import datetime

from verimem import Memory

m = Memory("memory.db", llm=my_llm)   # any client with .complete(system, messages)

# Store a conversation — facts are extracted atomically and pass the gate.
# user_name makes the app-provided identity the subject of the facts.
m.add([{"role": "user", "content": "I moved to Berlin in March."}],
      user_name="Alice")

# Store a single verified fact (no LLM needed)
m.add("Deploy pipeline is green", verified_by=["ci:main:green"])

# Search — optionally with history context or as of a past moment
m.search("where does Alice live?")
m.search("where did Alice live?", as_of=datetime(2024, 1, 1).timestamp())

# Ask HOW the system knows: evidence dossier or an explicit abstention
report = m.explain("where does Alice live?")

Quickstart (Claude Code / MCP)

Add to .mcp.json in your project (or ~/.claude/.mcp.json):

{
  "mcpServers": {
    "verimem": {
      "command": "engram",
      "args": ["mcp"],
      "env": { "ENGRAM_HOSTED": "1" }
    }
  }
}

This exposes the memory tools (hippo_remember, hippo_facts_recall, hippo_trust_report, hippo_document_semantic_search, …) to any MCP client.

CLI

verimem index contract.pdf              # index a document for semantic search
verimem search-docs "termination clause" # passages with file + offset citations
verimem import conversations.json       # list a ChatGPT/Claude export (imports nothing
                                        # until you pass --ids or --all)
verimem trust "the deploy is green" --verified-by ci:main:green
verimem airgap                          # verify a zero-egress configuration

Benchmarks

Measured on HaluMem with the full pipeline (our extraction → gated store → answer), judged by a Claude-based grader. Full methodology, caveats and raw result files: BENCHMARKS.md.

We describe the end-to-end result as parity, not a win: one run scored above MemOS's self-reported number, one just below, and the judges differ (ours vs theirs). Trust properties hold through the full pipeline. On TrustMem-Bench — six deterministic trust axes (fabrication under absence, destructive updates, temporal integrity, forget integrity, provenance honesty, sycophancy resistance) — Verimem scores 60/60; the bench is offline and seeded, run it yourself in one command.

Scale: recall latency stays ~flat with an ANN index (1.3 ms at 1M facts vs 81 ms brute-force — reproducible, see SCALE.md).

Architecture

conversations / documents / tool results
        │  atomic extraction (subject-named, date-attached)
        ▼
  admission gate  ── rejects unsupported & contradictory claims
        ▼
  bi-temporal store (SQLite) ── facts + provenance + supersession chains
        │
        ├─ semantic recall (local embeddings + ANN, optional reranker)
        ├─ history / as-of / transition context
        └─ TrustReport: evidence dossier or explicit abstention

The Python package is engram (the architecture name); verimem is the product and distribution name. Both import paths work.

License

Dual-licensed: AGPL-3.0 for open source use, with a commercial license available for proprietary or closed-SaaS deployments — see LICENSING.md. Versions 0.3.x and earlier remain MIT.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Development setup:

git clone https://github.com/aureliocpr-ctrl/verimem && cd verimem
pip install -e ".[dev]"
pytest -q