verifiable-memory-mcp

Local-first, append-only, tamper-evident memory for AI agents.

→ Landing page · → Interactive sandbox · → Evidence verifier

verifiable-memory-mcp is an MCP server for storing agent memory as a verifiable hash chain.

Every entry is immutable, timestamped, cryptographically linked to the previous one, and exportable as portable evidence.

This repository is a public, focused implementation of one idea: agent memory should not only be useful, it should also be inspectable and tamper-evident.

It is not presented as a full agent operating system, a full memory architecture, or a complete governance layer. It is a narrow, practical building block that demonstrates a specific capability clearly.

Why this exists

AI agents accumulate memory over time:

• decisions,
• operator notes,
• reminders,
• constraints,
• context,
• and historical records of what mattered.

In most systems, that memory is optimized for retrieval, not integrity.

Files get edited. Context drifts. Records are overwritten. Explanations come after the fact.

This project takes a different angle:

before asking whether an agent remembers well, ask whether its memory can be checked.

What it does

This server gives an MCP-compatible client a local memory store with:

• append-only writes,
• per-entry hashing,
• chain integrity verification,
• chronological inspection,
• portable export,
• a browser-based Evidence Record verifier.

The result is simple:

you can later verify whether what the agent “remembers” is still what was originally stored.

What it is not

This is not:

• a vector database,
• a semantic memory system,
• a long-context reasoning engine,
• an enterprise audit platform,
• or a complete agent governance framework.

It does not try to solve everything.

It focuses on one narrow property:

memory integrity.

Core idea

Each memory entry creates hashes that bind content, timestamp, and position in a chain.

contentHash = sha256(content)
entryHash   = sha256({ contentHash, prevHash, createdAt })

• contentHash checks the stored content itself
• prevHash links the entry to the previous entry
• entryHash checks the integrity of the whole record in context

If someone edits an entry directly, the content hash no longer matches. If someone inserts, removes, or reorders entries, the chain breaks.

Available tools

| Tool | Description | |---|---| | remember | Store a new memory entry (append-only, hash-chained) | | recall | Search memories by text content | | verify | Recompute hashes and confirm an entry has not been altered | | chain | Validate the full chain and detect breaks or reordering | | timeline | List memories chronologically, optionally filtered by tag | | export | Export a portable, verifiable Evidence Record |

Evidence packages and verifier

The primary evidence artifact is a portable .eco package. The verifier link or QR is only a fast way to open that package.

Each .eco file is a JSON evidence envelope with:

• bundleText: the exact exported Evidence Record (verifiable-memory-bundle internally),
• anchor.bundleHash: the Evidence Hash, the SHA-256 hash of that record,
• manifest: agent, cycle, decision, memory status, failed entry, and timestamp,
• report: a human-readable explanation of what happened.

The demo writes packages to:

demo/evidence/

Examples:

000_IDLE.eco
001_EXECUTE.eco
003_WAIT_FOR_OWNER.eco
005_STOP_BY_INTEGRITY.eco
latest.eco

This repository also includes a static verifier at:

verifier/index.html

It verifies .eco packages, .ecox replay packages, and exported Evidence Record files entirely in the browser. It checks entry content hashes, entry hashes, chain links, and optionally a SHA-256 anchor for the exact exported file. Strict mode lets a reviewer load the Evidence Record and ECO receipt as separate files and verify that they match.

For a local demo:

npm run demo:export
npm run demo:publish-local

Then open the .eco verifier URL printed by demo:export, or load:

demo/evidence/latest.eco

Standalone verifier mode is also available:

npm run demo:verifier

If the package was exported before tampering, the verifier should show INTACT. If it was exported after direct SQLite tampering, it should show ALTERED.

demo:publish-local serves the dashboard, verifier, and .eco files from one local origin. That makes this URL shape work for QR codes or another device on the same network:

http://<your-local-ip>:4190/verifier/index.html?eco=/evidence/latest.eco

To share a public verifier URL, set DEMO_PUBLIC_BASE_URL before exporting:

export DEMO_PUBLIC_BASE_URL=https://demo.example.com
npm run demo:export

The export script will print both the local and the public verifier URLs.

Phone/external device verification requires HTTPS for browser Web Crypto APIs. For judge or investor demos, use an HTTPS domain, a tunnel (ngrok, cloudflared), or drag-and-drop the .eco file into the standalone verifier as the reliable fallback.

Why MCP

This project is designed for the Model Context Protocol so that memory integrity can be exposed as a tool, not buried as an implementation detail.

That matters because it lets an agent:

• write memory,
• inspect memory,
• verify memory,
• and export memory evidence

through the same tool interface it uses for the rest of its work.

Example

Remember: The deployment strategy prioritizes Europe over Asia for Q3.
✓ remembered (mem_a1b2c3d4)

Recall deployment strategy
Found 1 entry

Verify mem_a1b2c3d4
✓ Entry is intact and chain-verified

Install

npm install -g verifiable-memory-mcp

Requires Node.js 18+.

MCP client config

{
  "mcpServers": {
    "verifiable-memory-mcp": {
      "command": "npx",
      "args": ["-y", "verifiable-memory-mcp"]
    }
  }
}

Direct usage

npx verifiable-memory-mcp

For testing with JSON-RPC:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0.1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"remember","arguments":{"content":"test decision","tags":["test"]}}}' \
  | npx verifiable-memory-mcp

MCP Inspector

npx -y @modelcontextprotocol/inspector npx -y verifiable-memory-mcp

Tool examples

remember

{
  "content": "The deployment targets Europe for Q3",
  "tags": ["strategy", "deployment"]
}

recall

{
  "query": "deployment"
}

timeline

{
  "includeContent": true
}

verify

{
  "id": "mem_a1b2c3d4"
}

chain

{}

export

{}

Storage

Data is stored locally in:

~/.verifiable-memory-mcp/memory.db

SQLite, WAL mode. No cloud. No telemetry. No login.

Override the data directory with:

VMCP_DATA_DIR=/tmp/vmcp-demo npx -y verifiable-memory-mcp

Demo flow

The end-to-end demo is sandbox-only by default:

npm run demo:e2e

This uses /tmp/vmcp-agent-demo and never exports ~/.verifiable-memory-mcp unless you explicitly opt into real data elsewhere.

For a step-by-step recording flow:

export VMCP_DATA_DIR=/tmp/transparent-agent-demo
npm run demo:scenario:reset
npm run demo:cycle
npm run demo:owner-update
npm run demo:cycle
npm run demo:prompt-injection
npm run demo:cycle
npm run demo:owner-approve
npm run demo:cycle
npm run demo:tamper
npm run demo:cycle-after-tamper
npm run demo:export
npm run demo:publish-local

Telegram demo control

The demo can also be controlled through a Telegram bot. It only accepts a fixed set of demo commands and runs the same local scripts as the terminal flow.

Required environment:

export TELEGRAM_BOT_TOKEN=...
export TELEGRAM_CHAT_ID=...
export VMCP_DATA_DIR=/tmp/transparent-agent-demo
export DEMO_PUBLIC_BASE_URL=http://<your-local-ip>:4190
npm run demo:telegram

Available bot commands:

/ready
/cycle
/owner_update
/prompt_injection
/approve
/reject
/tamper
/export
/eco
/status
/help

Search behavior

recall currently uses text-based retrieval, not embeddings.

That is a deliberate choice in this version.

This project is not competing on semantic recall quality. It is competing on whether memory can later be checked and exported in a verifiable way.

If you work across languages, bilingual entries or bilingual tags improve recall quality.

Comparison

| Feature | Vector DBs | Typical memory layers | verifiable-memory-mcp | |---|---|---|---| | Primary goal | Retrieval | Convenience | Integrity | | Search | Semantic | Mixed | Text | | Append-only | Usually no | Sometimes | Yes | | Chain verification | No | Rarely | Yes | | Local-first | Sometimes | Sometimes | Yes | | MCP-native | Varies | Varies | Yes |

One verification pattern, multiple applied workflows

This public integrity layer is one focused building block inside a wider architecture for portable evidence and independent verification.

These are not separate product claims. Every application below shares one discipline: a claim about information is only trustworthy if it can be checked against the record it came from, not taken on faith. Evidence travels in a portable package (ECO) that anyone can verify independently — outside the system that produced it.

ECO Evidence Package

Shared evidence packaging layer.

The bridge between memory, evidence, and verification: portable evidence packages that can be checked independently, outside the original system, across workflows, devices, and operators. The open verifier runs in the browser.

EcoSign

Commercial application in preparation.

Document and agreement workflows with verifiable evidence: integrity, export, and independent verification for document-centered work. Open verifier source: ecosign-public.

CustodyArt

Applied provenance and custody workflow.

Custody and evidence discipline for creative digital assets, where provenance and traceability matter over time. Sealing flow live: upload, fingerprint, witness, exportable evidence.

WITH

Roadmap — personal verifiable memory.

The same evidence-first principle applied to personal memory for AI assistants: answers that link back to the records that support them. In active development; core remains private.

Talo

Applied agent workflow — controlled demo.

Talo applies the same integrity-before-action pattern to recruiting operations: agents verify their memory before sourcing, pause for owner approval, and stop if the chain is broken. The same evidence format has been cross-validated at the byte level with this package. Private demo access — restricted.

Security / threat model

• Tamper detection: verify() detects altered entry content. chain() detects broken links, removals, and reordering.
• No encryption: the SQLite database is stored in plaintext.
• No access control: anyone with filesystem access can read the database.
• No cloud: the server does not send data to external services.
• Not a hardened audit appliance: if an attacker fully controls the machine, this tool does not guarantee safety.

This project helps detect memory changes. It does not guarantee system compromise resistance.

Positioning

The best way to understand this repository is:

a public, concrete demonstration that agent memory can be append-only, inspectable, and tamper-evident through MCP.

It is intentionally narrower than the broader architectural questions it points toward.

Strategy docs

• Transparent Agent Evidence
• ECO and ECOX Model
• ECO Verifier Universal Model

License

MIT