Related Pages

Related topics: MCP Server Architecture and Tools, Evidence System, Verifier and Anchors

Overview and Core Concepts

verifiable-memory-mcp is a Model Context Protocol (MCP) server that exposes a memory layer whose contents can be cryptographically verified end-to-end. The project pairs an in-memory knowledge store with a periodic "anchor" process that publishes a tamper-evident digest of the store to an external medium, so any consumer can later prove that a given memory existed in a specific state at a specific time.

Purpose and Scope

The server targets agents and tooling that need durable, recallable memory without trusting a single host. Every mutation of memory is recorded as a verifiable artifact, and the server ships a configurable anchor workflow that periodically commits the current state hash to a public, append-only log. The resulting "anchor" releases — distributed as bundle.json files with sha256(...) digests — form a chain that any third party can re-check independently. Source: README.md:1-40

The scope is intentionally narrow: the project owns the MCP transport, the in-memory store, the hashing primitives, and the anchor bundle format. It does not implement its own consensus layer or log; the anchor target is pluggable so the same server can publish to a transparency log, a notarization service, or another MCP-compatible storage endpoint. Source: src/anchor.ts:1-30

Memory Model and Core Types

The shared vocabulary lives in src/types.ts. Memory entries are typed records with a stable identifier, a payload, provenance metadata, and a content hash. Mutations are append-only in spirit: edits produce new entries that reference their predecessors, so the historical shape of the store can always be reconstructed by replaying the entry sequence. Source: src/types.ts:1-60

The graph abstraction lets a server hold multiple independent memory namespaces simultaneously, each with its own anchor cadence and verification key set. This makes it straightforward to isolate tenants or sub-agents inside one process without leaking state across them. Source: src/types.ts:60-120

Cryptographic Anchoring and Verification

Hashing and canonicalization are handled in src/hashing.ts. Entries are serialized with a deterministic encoder, then hashed with SHA-256 so that two clients computing the same logical memory always produce identical digests. This determinism is what makes the anchor workflow meaningful: any divergence between independent replays is detectable as a hash mismatch. Source: src/hashing.ts:1-50

Verification works in two directions:

• Forward verification — when an entry is written, the server recomputes the expected hash and stores it alongside the record so readers can confirm integrity without re-deriving it. Source: src/hashing.ts:50-90
• Backward verification — given a previously published anchor (e.g. Anchor 20260613T050846Z with sha256(bundle.json) = 62db7d73...437c), a client can fetch the current store, replay entries to compute the digest, and compare it to the anchored value. Source: src/anchor.ts:30-80

flowchart LR
  A[Memory Write] --> B[Deterministic Encode]
  B --> C[SHA-256 Digest]
  C --> D[MemoryEntry Stored]
  D --> E[Aggregate Graph Hash]
  E --> F[Anchor Bundle]
  F --> G[(External Log)]
  G --> H[Independent Verify]

MCP Server Interface and Configuration

The MCP transport layer is implemented in src/server.ts. It exposes the memory surface as a small set of tools and resources: reading memory, writing memory, listing namespaces, fetching the latest anchor, and verifying an attestation against an anchor. The server is launched as a stdio MCP server, which is the convention used by Claude and other MCP-compatible clients. Source: src/server.ts:1-70

Runtime configuration is driven by package.json and a small set of environment variables. The default entry point wires hashing, storage, and anchor scheduling into a single process, while letting operators swap the anchor target, the retention window, or the verification key set without touching the core code. Source: package.json:1-40

Releases follow the anchor naming convention seen in the community evidence (Anchor YYYYMMDDTHHMMSSZ). Each release pairs a tagged commit with the sha256(bundle.json) that downstream verifiers should expect, which is the contract that makes the whole memory layer independently auditable. Source: README.md:40-80

Related Pages

Related topics: Overview and Core Concepts, Evidence System, Verifier and Anchors

MCP Server Architecture and Tools

The verifiable-memory-mcp project implements a Model Context Protocol (MCP) server that provides agents and clients with a cryptographically verifiable long-term memory store. The server exposes two primary tools — remember and recall — over the standardized MCP transport, backed by a local SQLite-style database and a deterministic hashing layer that produces tamper-evident bundle anchors.

Server Entry Point and Tool Registration

The server is bootstrapped in src/index.ts, which configures the MCP transport, instantiates the database layer, and registers the available tools with the MCP runtime. The entry point acts as the composition root, wiring together hashing, persistence, and tool handlers before listening for JSON-RPC requests from MCP-compatible clients. Source: src/index.ts:1-40

Tool registration follows the MCP convention of declaring each tool's name, description, and input schema. The remember tool is registered to accept new memory entries, while the recall tool is registered to query previously stored entries. Both registrations share a consistent JSON-schema definition so clients can introspect parameters at runtime. Source: src/index.ts:42-80

Core Type Contracts

The shared type definitions in src/types.ts describe the canonical shapes of memory records, tool inputs, tool outputs, and verification artifacts. These types establish invariants that flow from the transport boundary all the way down to the database row format, ensuring that hashing and persistence operate on stable structures. Source: src/types.ts:1-30

Notable contracts include the MemoryEntry shape (containing payload, metadata, and timestamp), the Anchor shape returned by hashing operations, and discriminated unions for tool responses that distinguish successful results from verification failures. Source: src/types.ts:31-70

Verifiable Persistence Layer

The persistence layer in src/db.ts is responsible for storing memory entries and retrieving them by query. Each write produces a row that pairs the entry content with its cryptographic anchor, allowing the server to prove that a recalled entry corresponds to an entry that was previously written. Source: src/db.ts:1-50

Verification at the persistence layer relies on src/hashing.ts, which computes deterministic content hashes over serialized entry payloads. The hashing module is designed to be collision-resistant and reproducible, so that anchors computed at write time can be re-derived at read time and compared for integrity. Source: src/hashing.ts:1-45

The following table summarizes the flow of a verification check across these modules:

Tool Handlers: `remember` and `recall`

The remember tool handler in src/tools/remember.ts accepts a payload from the MCP client, validates it against the registered schema, constructs a MemoryEntry via the type contracts, computes its anchor, and delegates the actual write to the database layer. On success, it returns the entry identifier together with its anchor so the caller can later request verification. Source: src/tools/remember.ts:1-60

The recall tool handler in src/tools/recall.ts accepts a query — typically a key, identifier, or search predicate — and asks the database layer for matching entries. For each candidate entry, the handler triggers a re-hash and compares the freshly computed anchor against the stored anchor before returning the result. This re-hash-on-read pattern is what gives the tool its "verifiable" property: callers receive not only the entry but an attestation that it has not been altered since storage. Source: src/tools/recall.ts:1-70

Architectural Summary

At a high level, the server follows a layered architecture: transport and tool registration at the top (src/index.ts), strict type contracts (src/types.ts), tool-specific orchestration (src/tools/remember.ts, src/tools/recall.ts), and at the bottom a hashing module (src/hashing.ts) paired with a persistence module (src/db.ts). All verifiability guarantees flow from the deterministic interaction between the hashing layer and the anchor-paired storage layer, anchored externally by community-observed release bundles such as Anchor 20260613T050846Z and Anchor 20260613T032345Z whose bundle.json checksums are recorded in the community context.

Related Pages

Related topics: MCP Server Architecture and Tools, Demo Flows, Scenarios, Operations and Ecosystem

Evidence System, Verifier and Anchors

Purpose and Scope

The Evidence System is the trust layer of verifiable-memory-mcp: it converts the server's internal memory state into an exportable, content-addressed artifact and lets third parties confirm that a given artifact has not been silently mutated. The Verifier is the accompanying client-side tool that performs that confirmation, and Anchors are the periodic, signed time-stamps that bind successive bundles to a published history.

Together these three components answer a single question: *can an auditor reproduce the exact memory state that a server claims to have had at a given moment?* The Verifier and the Evidence System are designed to operate without access to the live MCP server — every check is performed against a static bundle.json, which makes independent verification possible from any machine with the right files.

Source: verifier/README.md:1-40

Bundle Format and the Export Pipeline

A *bundle* is the canonical evidence payload produced by the MCP server. It is generated by the export tool (src/tools/export.ts) and serialized as bundle.json. The bundle aggregates the memory records that the server persisted, plus metadata required to recompute its content hash. The Verifier never re-reads the server: it only inspects this file.

The content-addressing strategy uses SHA-256 over the canonicalized bundle, which means any byte-level change to a memory record produces a different digest. The same digest is later embedded in an Anchor, creating a tamper-evident chain across time. A small example of the layout is shipped alongside the Verifier to make the schema self-documenting.

Source: src/tools/export.ts:1-120, verifier/sample-bundle.json:1-60

The Verifier

The Verifier is implemented as a self-contained browser-based page (verifier/index.html) that loads the bundle, the expected anchor digests, and any auxiliary schemas, then walks the bundle to recompute its hash and compare it against the value stored in the matching Anchor.

The companion acceptance.mjs script reproduces the same logic from the command line using Node.js. Running the script on the included sample bundle is the canonical smoke test: it loads sample-bundle.json, recomputes the SHA-256, asserts that it matches the anchor digest pinned in the README, and exits non-zero if anything diverges. This dual surface — a human-friendly HTML page and a CI-friendly script — is intentional, so the same checks can run during development, in pull-request pipelines, and during external audits.

Source: verifier/index.html:1-200, verifier/acceptance.mjs:1-150

Anchors and the Anchor Script

An Anchor is a published declaration of the form:

*At time T, the SHA-256 of bundle.json is H.*

Anchors are released as GitHub release tags (e.g. anchor-20260613T050846Z) whose body pins the digest of a specific bundle, alongside the timestamp. Each Anchor supersedes the previous one in chronological order; consumers are expected to verify that the chain is monotonically increasing in time and that every digest in the chain matches a bundle they can independently obtain.

Source: verifier/README.md:40-120

The verifier/anchor.sh helper automates the operator side of this workflow: it resolves the current server state, invokes the export tool, computes the bundle digest, and emits the release-ready metadata that can be pasted into a new GitHub release. The two Anchors visible in the community context — Anchor 20260613T050846Z (62db7d73…437c) and Anchor 20260613T032345Z (feb535fc…7cd3) — are concrete examples of this output.

Source: verifier/anchor.sh:1-100

Verification Workflow

flowchart LR
    A[MCP Server state] --> B[export.ts]
    B --> C[bundle.json]
    C --> D[SHA-256 digest]
    D --> E[anchor.sh]
    E --> F[GitHub Release / Anchor]
    F --> G[(Public ledger)]
    C --> H[index.html / acceptance.mjs]
    F --> H
    H --> I{Hash match?}
    I -- yes --> J[Accepted]
    I -- no  --> K[Rejected]

The flow makes the trust boundary explicit: everything from bundle.json to the Anchor happens under operator control; everything from the public release to the Verifier runs on the auditor's machine. Any divergence between these two halves — including a tampered bundle, a swapped Anchor, or a missing release — surfaces as a non-zero exit from acceptance.mjs or a visible failure in the HTML verifier.

Source: verifier/acceptance.mjs:20-90, verifier/index.html:30-160, verifier/README.md:80-160

Operational Notes

• An Anchor is only meaningful if the corresponding bundle.json is also obtainable; the Verifier will reject an Anchor whose bundle is missing or whose hash disagrees.
• anchor.sh is the only step that requires write access to the release channel; everything else is read-only and safe to run in untrusted environments.
• Acceptance scripts are expected to be re-run on every new Anchor, providing a continuously-fresh negative test against back-dated or fabricated evidence.

Source: verifier/anchor.sh:40-100, verifier/acceptance.mjs:60-150

Related Pages

Related topics: MCP Server Architecture and Tools, Evidence System, Verifier and Anchors

Demo Flows, Scenarios, Operations and Ecosystem

The demo/ directory of verifiable-memory-mcp ships runnable end-to-end scenarios that exercise the server's verifiable-memory primitives, MCP client integration, and authorization flows. Together they form an executable reference for contributors integrating the system, and they double as living documentation for the operations surrounding the server.

Purpose and Scope of the Demo Suite

The demos are intentionally small, self-contained Node ES module scripts. Each script represents a distinct operational concern: bootstrapping, shared helpers, agent-driven memory writes, MCP client invocation, source-level update authorization, and owner approval. They are not unit tests; they are scenario walks that can be invoked against a running server to reproduce canonical behaviors.

• demo/setup.mjs is the entry point for preparing the demo runtime, ensuring the server, dependencies, and fixture data are in place before any scenario runs. Source: demo/setup.mjs
• demo/common.mjs centralizes reusable helpers (log formatting, request building, assertion helpers) so that scenario scripts stay focused on the narrative of the flow rather than boilerplate. Source: demo/common.mjs

The latest community anchor (anchor-20260613T050846Z, sha256 62db7d731117434c4893713584abaaaa3541a1f0bae702a34475af66a08c437c) bundles these scenarios together with a verifiable manifest, so consumers can reproduce exactly the flows described here. Source: https://github.com/TemporalDynamics/verifiable-memory-mcp/releases/tag/anchor-20260613T050846Z

Core Scenario Flows

Two scripts demonstrate the canonical memory write/read loop.

• demo/agent-loop.mjs walks an agent through the iterative cycle of recalling prior verifiable state, producing a new action, and writing back a verifiable record. It is the canonical "happy path" and is useful as a template when wiring any agent framework on top of the server. Source: demo/agent-loop.mjs
• demo/mcp-client.mjs exercises the server through an MCP client, demonstrating how a third-party process — not the server itself — drives the protocol. This is the script to study when integrating with Claude Desktop, Cursor, or any other MCP host. Source: demo/mcp-client.mjs

Authorization and Governance Scenarios

Because the system is built around *verifiable* memory, write authorization is a first-class concern. Two scripts show how writes are gated.

• demo/authorized-source-update.mjs shows an already-authorized source performing a memory update. The source proves authority inline as part of the update payload, and the server accepts the write without an out-of-band approval step. This models trusted integrations such as a signed publisher or an internal automation. Source: demo/authorized-source-update.mjs
• demo/owner-approve.mjs shows the contrasting case: a source submits an update that requires explicit human owner approval. The script stages the request, performs the approval, and then confirms the resulting verifiable record. Together these two flows illustrate the two-step governance model. Source: demo/owner-approve.mjs

Operations and Ecosystem

Operationally, the demo suite is the primary on-ramp for new users: setup.mjs provisions state, common.mjs removes duplication, and the four scenario scripts each map to one operational pattern (agent loop, MCP client, authorized source, owner approval). The ecosystem dimension is reflected in the anchor releases — each anchor pins the demo scenarios to a specific bundle hash so that downstream consumers, audits, and reproducible benchmarks can cite an exact behavior snapshot. Source: https://github.com/TemporalDynamics/verifiable-memory-mcp/releases/tag/anchor-20260613T032345Z

For maintainers, the demos serve as the de facto integration test surface; for integrators, they are the fastest way to learn the protocol's request shapes and authorization semantics without reading the server's internals.

Source File Summary

Doramagic Pitfall Log

Found 6 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Capability evidence risk - Capability evidence risk requires verification.

1. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/TemporalDynamics/verifiable-memory-mcp

2. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/TemporalDynamics/verifiable-memory-mcp

3. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/TemporalDynamics/verifiable-memory-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/TemporalDynamics/verifiable-memory-mcp

5. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/TemporalDynamics/verifiable-memory-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/TemporalDynamics/verifiable-memory-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using verifiable-memory-mcp with real data or production workflows.

• Anchor 20260613T050846Z - github / github_release
• Anchor 20260613T032345Z - github / github_release
• Capability evidence risk requires verification - GitHub / issue