cryptomem

Cryptographically verified, relational, persistent memory for AI agents — any model, any size, local-first.

Why · Architecture · Quickstart · Docs · Roadmap · Contribute

Note

Status: published and installable. The Python engine is on PyPI (pip install cryptomem) and the typed Rust client SDK is on crates.io (cargo add cryptomem-rs), with tagged GitHub Releases carrying both artifacts. It provides SHA-256/Ed25519 signed memory with Merkle inclusion proofs, vector + knowledge-graph retrieval, a strict grounding gate, accuracy pillars (faithfulness, citations, semantic-entropy confidence, Chain-of-Verification), proactive memory (planner / triggers / write-back), BYOK key providers, and SQLite / Neo4j / remote-backend stores behind an Ollama-compatible sidecar. The Rust client signs nodes client-side that the Python engine verifies byte-for-byte. Early 0.1.x line — see ROADMAP.md for the path to 1.0.

---

Why

Small/local language models are cheap and private but hallucinate and lack persistent, verifiable memory. cryptomem gives any model — including tiny local Ollama SLMs — a relational, persistent, cryptographically verified memory.

🔐 Verifiable, not trust-based Every fact is hashed (SHA-256) and signed (Ed25519). Tampered or unverified facts are never injected — the agent abstains instead of guessing. 🕸️ Relational persistence GraphRAG-style nodes + edges. SQLite by default; a graph-native Neo4j store and a zero-trust remote ledger backend are first-class and selectable by config.

🦀 Works from Python and Rust A FastAPI Ollama-compatible sidecar lets any Ollama client get verified memory by changing only the base URL — zero inference-code changes. 🪶 Token-efficient & potato-friendly retrieve → dedupe → rank → budget → compress → cache. Runs and tests on an 8 GB, CPU-only laptop (mock mode needs no models at all).

Note

Honesty as a feature: the ~90% hallucination-reduction / >95% accuracy targets hold under closed-domain, abstention-allowed conditions on a defined benchmark — the exact conditions are documented in docs/accuracy_and_hallucination.md.

---

How a fact becomes a trusted answer

How it crosses languages

flowchart TD
    PY[Python: ollama lib] -->|Mode A: import| SDK[cryptomem SDK]
    PY -->|Mode B: base_url| PROXY[cryptomem Sidecar :8088]
    RS[Rust: ollama-rs] -->|Mode B: base_url| PROXY
    SDK --> ENGINE[cryptomem Engine]
    PROXY --> ENGINE
    ENGINE -->|verify + retrieve + compress| STORE[(Verified Memory Store)]
    ENGINE -->|enriched prompt| OLLAMA[Ollama :11434]
    OLLAMA --> ENGINE

Loading

The sidecar speaks Ollama's own wire protocol, so any Ollama client works unmodified. Full API in docs/api_documentation.md.

---

Quickstart

# 1) a tiny local model
ollama pull qwen2.5:0.5b
ollama serve

# 2) install the verified-memory engine from PyPI and run the sidecar in front of it
pip install "cryptomem[serve,local]"
cryptomem serve --port 8088 --ollama-url http://localhost:11434

Rust client: cargo add cryptomem-rs. Both packages are published — PyPI · crates.io. (Developing on the repo? Install from source with pip install -e "./python[serve,local]".)

The sidecar defaults to the local SQLite store. Select a different backend with CRYPTOMEM_* env vars — e.g. CRYPTOMEM_MODE=neo4j (with pip install "cryptomem[neo4j]" and CRYPTOMEM_NEO4J_URI=...) or CRYPTOMEM_MODE=remote with CRYPTOMEM_BACKEND_URL=... (falls back to SQLite if the backend health check fails, so edge devices stay online).

Point your existing client at the sidecar:

from ollama import Client
client = Client(host="http://127.0.0.1:8088")   # cryptomem, not :11434
resp = client.chat(model="qwen2.5:0.5b",
                   messages=[{"role": "user", "content": "What budget did Project Phoenix get?"}])
print(resp["message"]["content"])   # answered only from verified memory, or abstains

// Rust: same idea via ollama-rs — just point at the sidecar host/port.
use ollama_rs::Ollama;
let ollama = Ollama::new("http://127.0.0.1".to_string(), 8088);

---

Documentation

Doc	Purpose
docs/research_overview.md	Start here — problem, decisions, document map.
docs/cryptographic_memory.md	Architecture & concepts.
docs/implementation_plan.md	Engineering blueprint (modules, data model).
docs/api_documentation.md	Sidecar + native REST API; Python & Rust.
docs/accuracy_and_hallucination.md	Reaching the accuracy targets; eval harness.
docs/low_spec_hardware.md	Running/developing on a low-spec laptop.
docs/hermes_integration.md	Flagship NousResearch Hermes agent integration.
docs/framework_integrations.md	Verified memory in agno (Python) & swarms-rs (Rust).
docs/packaging_and_release.md	PyPI / crates.io release strategy.

---

Ecosystem & framework integrations

cryptomem drops into the agent frameworks you already use — answers stay grounded in signed facts, and the agent abstains rather than hallucinates.

Framework	Language	Runnable example	How
agno	Python	python/examples/agno_verified_memory.py	Verified-memory tools backed by an in-process engine.
swarms-rs	Rust	rust/examples/swarms-verified-memory	A Tool that queries the sidecar via cryptomem-rs.
hermes-agent	Any model	docs/hermes_integration.md	Sidecar as the model endpoint, or verified memory as an MCP/tool/skill.

Full guides: docs/framework_integrations.md and docs/hermes_integration.md. These integrations are offered back to the agno, swarms-rs, and hermes-agent communities — see the release announce step in docs/packaging_and_release.md.

hermes-agent verified-memory skill — up for review with Nous Research

We're packaging the verified-memory integration as a hermes-agent skill (agentskills.io standard) — memory_search / memory_add / memory_verify / memory_proof backed by the cryptomem sidecar — so a self-improving Hermes agent only ever recalls signature-verified facts and abstains instead of guessing. The design is in docs/hermes_integration.md §6 and is submitted for review with the NousResearch team and hermes-agent maintainers.

Tagging the hermes-agent maintainers / contributors for review and feedback — thank you for building Hermes: @NousResearch · @teknium1 · @OutThisLife · @kshitijk4poor · @0xbyt4 · @benbarclay · @alt-glitch · @helix4u · @austinpickett · @ethernet8023 · @briandevans.

Reviewers: the skill spec, tool schemas, and grounding guarantee are in docs/hermes_integration.md §4 + §6; feedback via Issues or the hermes-agent Discord is welcome.

Project status & roadmap

Published and installable today — pip install cryptomem (PyPI) and cargo add cryptomem-rs (crates.io), with tagged GitHub Releases. See ROADMAP.md for the SemVer release train (v0.1 → v1.0). This is a monorepo: python/ (cryptomem → PyPI) and rust/ (cryptomem-rs → crates.io).

Contributing

Contributions welcome! Read CONTRIBUTING.md and our CODE_OF_CONDUCT.md. Look for good first issue labels. Report security issues privately per SECURITY.md.

License

Dual-licensed under either of MIT or Apache License 2.0 at your option. The Apache-2.0 option provides an explicit patent grant, which matters for the cryptographic code.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.