provara-mem

Drop-in claude-mem replacement. Same four MCP tools your agents already use — cryptographic hash chain underneath.

One config line. Zero prompt changes. Your agent's memory becomes tamper-evident.

Why Switch?

| | claude-mem | provara-mem | |---|---|---| | Tools | search, timeline, get_observations, save_memory | Same four — identical interface | | Storage | SQLite database | Append-only NDJSON vault | | Integrity | Trust the file system | Ed25519-signed, SHA-256 hash-chained | | Tampering | Undetectable | Cryptographically impossible without breaking the chain | | Portability | Locked to one machine | Copy the vault file. That's the migration. | | Recovery | Backup and pray | provara-mem verify — proves every event since genesis | | Prompt changes | — | Zero. Same tool names, same parameters, same responses | | Lock-in | Vendor database | Open NDJSON. cat your vault anytime. | | Price | Free | Free (local). $9/mo (cloud-synced vaults — coming soon). |

Install

npm (recommended)

npm install -g provara-mem

Bootstraps an isolated Python environment automatically. No pip step needed.

PyPI

pip install provara-mem

From source

cd tools/provara-mem && pip install -e .

Migration from claude-mem (30 seconds)

Step 1: Disable claude-mem

claude mcp remove claude-mem

Step 2: Initialize vault

provara-mem init

Creates ~/.provara/agent-memory/ with a fresh cryptographic vault.

Step 3: Register provara-mem

Claude Code CLI:

claude mcp add provara-mem -e PROVARA_MEM_VAULT=~/.provara/agent-memory -- provara-mem

Or add to settings.json:

{
  "mcpServers": {
    "provara-mem": {
      "command": "npx",
      "args": ["-y", "provara-mem"],
      "env": {
        "PROVARA_MEM_VAULT": "~/.provara/agent-memory"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "provara-mem": {
      "command": "npx",
      "args": ["-y", "provara-mem"],
      "env": {
        "PROVARA_MEM_VAULT": "~/.provara/agent-memory"
      }
    }
  }
}

That's it. Your agent's next save_memory call lands in a signed vault.

Tool Contract

provara-mem is a zero-prompt-change replacement. Same tool names, same parameters, same return shapes.

| Tool | Parameters | What It Does | |---|---|---| | save_memory(text, title?, project?) | text: string, title?: string, project?: string | Append a signed, hash-chained memory event | | search(query?, limit?, project?, type?, dateStart?, dateEnd?) | query?: string, limit?: int (default 20) | Find candidate memories — lightweight results (~50-100 tokens) | | timeline(anchor?, query?, depth_before?, depth_after?) | anchor?: event ID, query?: string | Pull chronological context around an event | | get_observations(ids, orderBy?, limit?) | ids: list[string] | Fetch full event payloads (~500-1000 tokens each) |

3-Layer Workflow (same as claude-mem)

1. search — Broad discovery. Returns IDs + titles + tags. Cheap.
2. timeline — Chronological context around a specific event. Medium cost.
3. get_observations — Full payloads by ID. Use sparingly.

Agent Boot Instructions (SWARM-DNA v1.2.0)

provara-mem ships with default agent boot logic compatible with the SWARM-DNA v1.2.0 genome:

LOAD  → Pull vault state. Verify hash chain integrity.
PATCH → Apply role context from AGENTS.md (if present).
MODE  → Default: chase_mode. Override via PROVARA_MEM_MODE env var.
COLD  → Execute verification protocol on first write.
READY → Log boot event to vault. Agent is live.

The agent creates the vault, not the developer. On first save_memory call, if no vault exists, provara-mem auto-initializes one at ~/.provara/agent-memory/. The boot event is the first link in the hash chain.

See BOOT.md for the full agent boot specification.

CLI Commands

provara-mem init                    # Create a new vault
provara-mem verify                  # Verify chain integrity (every event, every hash)
provara-mem show --last 10          # Show recent events
provara-mem search "query"          # Search the vault
provara-mem tags                    # List all tags
provara-mem                         # Start MCP server (stdio)

Environment Variables

| Variable | Default | Purpose | |---|---|---| | PROVARA_MEM_VAULT | ~/.provara/agent-memory | Vault directory path | | PROVARA_MEM_MODE | chase_mode | SWARM-DNA mode override | | PROVARA_MEM_AUTO_INIT | true | Auto-create vault on first write |

Verify Your Chain

provara-mem verify

This walks every event in the vault, recomputes SHA-256 hashes, verifies Ed25519 signatures, and confirms chain integrity from genesis to HEAD. If any event has been tampered with, modified, or deleted — verification fails.

"Truth is not merged. Evidence is merged. Truth is recomputed."

Smoke Test

provara-mem init
provara-mem verify
python3 - <<'PY'
import json, subprocess

proc = subprocess.Popen(
    ["provara-mem"],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
)
msg = {
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {
        "protocolVersion": "2025-11-05",
        "capabilities": {},
        "clientInfo": {"name": "smoke", "version": "0.0.0"},
    },
}
payload = json.dumps(msg)
proc.stdin.write(f"Content-Length: {len(payload)}\r\n\r\n{payload}")
proc.stdin.flush()
print(proc.stdout.readline().strip())
proc.terminate()
PY

License

Apache 2.0