DOCUMENTATION

The sovereign knowledge layer for artificial intelligence.

VISION

ChainMemory is not a memory tool. It is a sovereign knowledge layer for AI systems.

Every AI model today suffers from the same fundamental limitation: when a conversation ends, everything learned disappears. Context is lost. Decisions are forgotten. Progress resets to zero. ChainMemory exists to solve this permanently.

The memories you save are the mechanism. The Project State — a structured, versioned, consolidated view of your project's knowledge — is the product. The blockchain is the proof. And interoperability between any AI model is the consequence.

What ChainMemory Enables

• Portable memory across models — Your knowledge works with ChatGPT today, Claude tomorrow, and any future model. No vendor lock-in, ever.
• Verifiable continuity — Every project state is anchored on-chain with a cryptographic proof. You can demonstrate that a decision existed at a specific moment in time.
• Decision audit trail — Every decision traces back to the conversations that produced it. Full provenance, full accountability.
• Persistent identity for AI workflows — Your AI assistant doesn't start from zero each session. It inherits the accumulated knowledge of every previous interaction.
• Sovereign knowledge — You own your data. Not OpenAI, not Anthropic, not Google. Your memories live in your account, anchored to a public blockchain you can verify independently.

WHAT IS CHAINMEMORY

ChainMemory is a platform for persistent, portable, and verifiable memory for artificial intelligence. Every important conversation, every decision, every project context is saved as an individual memory, linked to a project, and anchored on a sovereign blockchain.

Your AI forgets every time you close the tab. ChainMemory solves that. It works with ChatGPT, Claude, Gemini, Copilot, Perplexity and any model that supports MCP or API.

WHY CHAINMEMORY

The problem is invisible until you've lost weeks of work

Every AI conversation today is a blank slate. The AI doesn't remember what you decided yesterday, what architecture you chose last week, or why you rejected an approach three months ago. Teams using AI accumulate critical knowledge — then lose it when the tab closes.

Before & after

What makes it different

Other tools save conversations. ChainMemory saves knowledge — structured, verified, and portable. The difference:

• Structured, not raw — The Consolidation Engine extracts decisions, milestones, risks, and stack from raw conversations. You get a Project State, not a transcript dump.
• Verified, not trusted — Every state is hashed and anchored on-chain. Anyone can verify independently without relying on ChainMemory's servers.
• Portable, not locked — Works across ChatGPT, Claude, Gemini, Copilot, Perplexity, and any MCP-compatible tool. Your knowledge moves with you.
• Injected, not searched — Context is automatically injected into new AI conversations. The AI gets what it needs without you copy-pasting anything.

QUICKSTART

Store → Retrieve → Verify → Prove in 5 minutes

Prerequisites

• Google Chrome (or any Chromium browser)
• A ChainMemory account — create one here
• Your API Key (from the Extension settings or dashboard)

Option A — Chrome Extension (fastest)

Option B — MCP Server (for Claude / Cursor)

Option C — REST API (full control)

Option D — Hermes Agent

Hermes Agent is an open-source AI agent framework. Use ChainMemory inside Hermes via the MCP server (native tools in chat) or the cm.py CLI wrapper (full terminal control).

Configure MCP

Edit ~/.hermes/config.yaml and add:

YAML
mcp_servers:
  chainmemory:
    command: "python"
    args: ["C:\\Users\\\\.hermes\\skills\\chainmemory-mcp\\chainmemory_mcp_server.py"]
    env:
      CHAINMEMORY_API_KEY: "aic_..."

Restart Hermes. Tools appear as mcp_chainmemory_* in chat.

Or use cm.py CLI

Install the ChainMemory skill and use cm save, cm recall, cm state from terminal.

Verify

In Hermes chat: "Remember: we decided to use PostgreSQL". Or run cm whoami in terminal.

bash
# 1. Store a memory
curl -X POST https://api.chainmemory.ai/v1/memory \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary":"Decided to use PostgreSQL for user DB","category":"decision","importance":8}'

# 2. Retrieve memories
curl https://api.chainmemory.ai/v1/memories/list?project=my-project \
  -H "x-api-key: YOUR_API_KEY"

# 3. Get project state (includes hash)
curl https://api.chainmemory.ai/v1/project/my-project/state \
  -H "x-api-key: YOUR_API_KEY"

# 4. Verify anchor (public — no auth needed)
curl https://api.chainmemory.ai/v1/project/my-project/state/anchor

CREATE YOUR ACCOUNT

Sign Up

ChainMemory accounts are created through the Chrome Extension. Your account gives you access to all three integration methods: Extension, MCP Server, and REST API.

Create Your First Project

Projects group related memories together. Each project has its own timeline, consolidated state, and independent on-chain anchor.

bash
curl -X POST https://api.chainmemory.ai/v1/projects \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-saas", "description": "My SaaS product"}'
    

Credentials Summary

ARCHITECTURE

ChainMemory has a 3-layer architecture:

Layer 1: Capture

The Chrome extension, MCP server, or direct API calls capture content from AI conversations. Content is processed, tagged, and linked to a project.

Layer 2: Storage & Consolidation

Each memory is stored in the episodic database with its SHA-256 hash. The Consolidation Engine analyzes memories and extracts structured operations: decisions, milestones, risks, tech stack, dependencies.

Layer 3: On-Chain Verification

The consolidated state of each project is periodically anchored on the ChainMemory blockchain (Chain ID 202604). The state hash is recorded in the ProjectStateAnchor contract, creating an immutable proof that this state existed at that moment.

Pipeline
AI Conversation
      |
  Extension / MCP / API
      |
  Memory (SHA-256 hash)
      |
  Consolidation Engine (AI model)
      |
  Project State (decisions, milestones, risks, stack)
      |
  Anchor on-chain (tx hash + block number)
      |
  Public verification (/v1/project/:name/state/anchor)

HOW CHAINMEMORY COMPARES

ChainMemory operates in the emerging space of AI memory infrastructure. Here's how it compares to the major solutions in 2026:

Overview Matrix

Detailed Comparisons

ChainMemory vs. Mem0

Mem0 focuses on user personalization — extracting facts from conversations to build user profiles. ChainMemory focuses on project knowledge — extracting decisions, milestones, and risks to build auditable project state. Mem0 is ideal for "remember the user prefers dark mode". ChainMemory is ideal for "prove that this architectural decision was made on May 15 by Claude based on these 5 conversations".

ChainMemory vs. Zep / Graphiti

Zep's Graphiti engine excels at temporal knowledge graphs — tracking when facts became valid and when they were superseded, with hybrid retrieval (semantic + BM25 + graph traversal). ChainMemory provides similar temporal supersession semantics but adds a layer Zep doesn't have: on-chain anchoring. When you need to prove to a regulator or auditor that a decision existed at a specific time, ChainMemory provides cryptographic proof. Zep provides trust-based assurance.

ChainMemory vs. Cognee

Cognee is a powerful data processing pipeline — ingesting 30+ sources, building knowledge graphs with subject-relation-object triplets, supporting multiple graph backends (Neo4j, FalkorDB, NetworkX). ChainMemory is more opinionated: it processes only AI conversation memories, but extracts structured project intelligence (6 categories) rather than generic knowledge graph nodes. Cognee is better for RAG enhancement over heterogeneous data. ChainMemory is better for project management and decision traceability.

ChainMemory vs. Supermemory

Supermemory focuses on semantic memory at scale — lightweight, fast, runs locally, top-ranked on memory benchmarks (LongMemEval, LoCoMo). ChainMemory is optimized for structured project knowledge with blockchain verification. Supermemory is the best choice for coding agents that need fast semantic recall. ChainMemory is the best choice when you need to prove what an AI decided and why.

CONCEPTS

The Event-Sourcing Model

ChainMemory follows an event-sourcing architecture. Understanding this pattern is key to understanding the entire system.

In traditional systems, you store the current state and overwrite it on each change. In event-sourcing, you store every change as an immutable event, and the current state is derived by replaying those events.

In ChainMemory:

• Memories are events — Each memory is an immutable record of something that happened: a decision was made, a risk was identified, a technology was chosen, a milestone was reached.
• Project State is a materialized view — The Consolidation Engine processes all memory-events and produces a structured snapshot: the Project State. This is not stored directly — it's computed from the event log.
• The blockchain is the timestamp authority — When a Project State is anchored on-chain, the blockchain certifies that this specific materialized view existed at that exact block height.

Pattern
Memory #1 (event) ─┐
Memory #2 (event) ─┤
Memory #3 (event) ─┼──→ Consolidation Engine ──→ Project State v1 ──→ Anchor (block 120000)
Memory #4 (event) ─┤
Memory #5 (event) ─┘

Memory #6 (event) ─┐
Memory #7 (event) ─┼──→ Consolidation Engine ──→ Project State v2 ──→ Anchor (block 123539)
Memory #8 (event) ─┘

This means you can always reconstruct any version of the Project State by replaying memories up to that point. The event log is the source of truth. The state is a convenience layer. The anchor is the proof.

What is a Memory

A memory is the fundamental unit of ChainMemory. It is a fragment of information extracted from an AI conversation that is considered valuable for the project's future.

Each memory contains:

• Content — The text of the conversation or note
• Hash — SHA-256 of the content, immutable
• Project — Which project it belongs to
• Tags — Free-form labels for organization (decision, bug, architecture, idea, etc.). Tags are for your use — the Consolidation Engine uses its own 6-category structure (see Project State)
• Number — Sequential within your account (#1, #2...)
• Source — Where it was saved from (extension, MCP, API)
• Timestamp — Exact moment of creation

Projects

A project groups related memories. Each project has its own timeline, consolidated state, and independent on-chain anchor.

Example projects: my-saas, ml-thesis, chainmemory, mobile-app.

Project State

The Project State is the output of the Consolidation Engine: an AI model analyzes all project memories and extracts structured information. It is the heart of ChainMemory — turning raw conversation fragments into an organized, auditable project knowledge base.

The 6 Categories

State Lifecycle

The state is incremental: each consolidation starts from the previous version and applies only new operations. This creates a version chain with full integrity:

Version chain
v1 (3 memories)  ──hash──▶  v2 (8 memories)  ──hash──▶  v3 (15 memories)
     │                           │                           │
     └─ anchored block 80,467   └─ anchored block 81,102   └─ anchored block 82,340

Each version contains:

• state_hash — SHA-256 of the entire state, linking to the previous version
• version — Sequential number (v1, v2, v3...)
• previous_hash — Hash of the prior version (null for v1)
• operations — What changed: additions, updates, supersessions
• anchor_tx — On-chain transaction hash (once sealed)

Real Example: Complete Project State

JSON — Project State v4
{
  "project_id": "payment-system-v2",
  "version": 4,
  "state_hash": "a3f8c2...e91d",
  "previous_hash": "7b2e1a...f4c0",
  "context": {
    "summary": "Payment processing system with multi-tenant isolation and fraud detection",
    "goals": ["Process 1000 tx/sec", "PCI DSS Level 1 compliance", "Sub-200ms latency"]
  },
  "decisions": [
    {
      "id": "d001", "title": "Use Stripe for payment processing",
      "status": "active", "evidence": ["#12", "#45", "#67"],
      "rationale": "Best API documentation, webhook reliability, PCI compliance built-in"
    },
    {
      "id": "d002", "title": "PostgreSQL with RLS for multi-tenancy",
      "status": "active", "evidence": ["#15", "#23"],
      "rationale": "Row-level security eliminates app-layer tenant filtering bugs"
    },
    {
      "id": "d003", "title": "Use MySQL for multi-tenancy",
      "status": "superseded", "superseded_by": "d002", "evidence": ["#8"],
      "rationale": "Initially chosen, replaced after RLS evaluation"
    }
  ],
  "milestones": [
    {"id": "m001", "title": "Database schema", "status": "completed", "date": "2026-05-15", "evidence": ["#23"]},
    {"id": "m002", "title": "Payment integration", "status": "pending", "evidence": ["#45"]}
  ],
  "risks": [
    {"id": "r001", "title": "RLS performance at 100K tenants", "severity": "medium", "evidence": ["#15", "#30"]}
  ],
  "stack": [
    {"name": "Node.js", "version": "22", "role": "runtime"},
    {"name": "PostgreSQL", "version": "16", "role": "primary-db"},
    {"name": "Redis", "version": "7", "role": "cache"},
    {"name": "Stripe", "role": "payment-provider"}
  ],
  "dependencies": [
    {"name": "Stripe API", "type": "external", "critical": true},
    {"name": "SendGrid", "type": "external", "critical": false}
  ]
}

Consolidation Engine Operations

When new memories arrive, the engine performs these operations on the state:

• ADD — New decision, milestone, risk, or stack entry detected in memory content
• UPDATE — Existing entry gets new evidence, updated status, or enriched details
• SUPERSEDE — A decision is replaced by a newer one (both preserved in history)
• COMPLETE — A milestone moves from pending to completed with a date
• ESCALATE — A risk severity increases based on new evidence

Best Practices

• Save decisions explicitly — "We decided to use X because Y" consolidates better than "maybe we should try X"
• Include rationale — The engine extracts rationale from memory content. The more context you provide, the richer the state
• Seal regularly — Anchor your state on-chain after major milestones to create immutable checkpoints
• Review superseded decisions — They tell the story of how your project evolved. Don't ignore them

Evidence Chain

Every decision, milestone, and risk in the Project State carries an evidence field — an array of memory references that justify its existence.

JSON
{
  "id": "d001",
  "title": "Use Clique PoA consensus",
  "statement": "Sovereign blockchain uses Proof of Authority for fast, low-cost anchoring",
  "status": "active",
  "evidence": ["#12", "#45", "#67"]
}

This creates a full provenance chain:

• Decision d001 exists because memories #12, #45, and #67 support it
• Each memory has a SHA-256 hash proving its content hasn't changed
• The Project State containing this decision has a state_hash anchored on-chain
• The on-chain anchor has a tx_hash and block number proving when it was registered

From a single decision, you can trace the full path: decision → supporting memories → content hashes → state hash → on-chain proof. This is what makes ChainMemory decisions auditable and tamper-proof.

Conflict Resolution

When two memories contain contradictory information, the Consolidation Engine applies a deterministic resolution strategy:

Temporal precedence

The most recent memory takes priority. If Memory #20 says "We'll use PostgreSQL" and Memory #40 says "Switching to ClickHouse", the engine marks the PostgreSQL decision as superseded and creates a new active decision for ClickHouse.

Explicit supersession

The engine detects language patterns indicating a change of direction: "instead of", "replacing", "we decided to switch", "no longer using". When detected, the previous decision is explicitly marked as superseded with a reference to the new one.

Status lifecycle

Every decision follows this lifecycle:

Status flow
active ──→ superseded    (replaced by a newer decision)
active ──→ evaluating    (under review, not yet confirmed)
evaluating ──→ active    (confirmed after evaluation)
evaluating ──→ rejected  (discarded)

Evidence accumulation

When multiple memories reinforce the same decision, the engine adds them to the evidence array rather than creating duplicates. A decision with evidence from 5 memories is stronger than one with a single reference.

State Governance

The Project State lifecycle is governed by clear rules:

Who can consolidate?

Only the project owner (the account that created the project) can trigger a consolidation. This ensures that the structured knowledge extraction is always controlled by the data owner.

When does consolidation happen?

Consolidation can be triggered in two ways:

• Manual — Via the MCP tool chainmemory_seal, the API, or the extension's Project Brain view
• Automatic — After a configurable number of new memories (default: every 10 new memories)

Can it be reverted?

Each consolidation creates a new version (v1, v2, v3...). Previous versions remain accessible. You cannot delete a version, but you can always consolidate again to produce a corrected state. The version chain is append-only.

Snapshots

Every Project State version is a snapshot. The combination of version number + state_hash + on-chain anchor creates a verifiable checkpoint. You can fetch any historical version via GET /v1/project/:name/state?version=2.

Hash & Verification

Each memory generates a SHA-256 hash of its content. This hash is the unique, immutable fingerprint of that memory. Content cannot be modified without changing the hash.

The state hash is a hash of the complete consolidated state (all decisions, milestones, risks, etc.). This state hash is anchored on the blockchain via a transaction on the ProjectStateAnchor contract.

Public verification

Verification in ChainMemory is public and permissionless. Anyone can:

1. Call GET /v1/project/:name/state/anchor (no API key required)
2. Get the state_hash and the tx_hash of the transaction
3. Verify on the explorer that the transaction exists
4. Read the contract directly on the blockchain to confirm the hash matches

This proves the project state existed exactly as described at the time of anchoring. It cannot be falsified retroactively.

Privacy Model

A common concern with blockchain-based systems is data exposure. ChainMemory addresses this with a strict separation:

What is stored where

The on-chain record contains only: project identifier (hashed), state version number, state hash, and timestamp. From a blockchain transaction, it is impossible to reconstruct the content of any memory or the details of any decision.

This design means ChainMemory can provide cryptographic verification without compromising privacy. The blockchain proves that a state existed, not what it contained.

CHROME EXTENSION

Installation

1. Go to the Chrome Web Store
2. Click "Add to Chrome"
3. The ChainMemory icon appears in the extensions bar
4. Click the icon and choose how to start: "Generate API Key automatically" (free, recommended) or "I already have a key" to paste an existing one
5. Select or create a project

Save Memories

From any supported AI chat, the extension automatically detects the active conversation. You have two ways to save:

Floating button

A gold button appears in the corner of the chat. One click extracts the conversation content, processes it, and saves it as a memory.

Extension popup

Click the ChainMemory icon in the browser bar. Select the target project, add optional tags, and confirm.

Rescue your history

You don't have to start from zero. The extension can save messages from your existing chat history — conversations from weeks or even months ago. Open any past conversation in a supported AI, and the "Save to ChainMemory" option works on older messages just as it does on a live chat.

This means the knowledge you've already accumulated across your AI conversations becomes sovereign, portable memory from day one. Once saved, you assign each memory to the project you want — an existing one or a new project — and organize it like any other.

Each saved memory receives:

• SHA-256 hash unique to the content
• Sequential number within your account (#1, #2, #3...)
• Tags for organization (decision, architecture, bug, etc.)
• Link to the active project
• Timestamp of the moment of saving

Inject Context

The most powerful feature: before starting a new conversation with any AI, ChainMemory can automatically inject the relevant context from your previous memories.

This means your new conversation starts with the accumulated knowledge of previous conversations. Your AI knows what you decided, what technologies you use, what your priorities are.

How it works

1. Open a new chat on any supported platform
2. The extension detects the text field
3. Select the memories or project state to inject
4. Context is automatically inserted as the first message

Project Brain (Project State Viewer)

Project Brain is the extension's built-in Project State viewer — a consolidated, structured view of everything your project knows. The Consolidation Engine analyzes all your memories and extracts:

• Decisions — What was decided and why (status: active, superseded, evaluating)
• Milestones — Completed and pending achievements with dates
• Risks — Identified threats with severity and status
• Tech stack — Project tools and technologies
• Dependencies — External relationships
• Context — Executive summary of the project

This state has a verifiable fingerprint anchored on-chain. You can prove that your project had exactly this state at a given moment.

Supported Platforms

The extension works with any web-based AI chat:

• ChatGPT (chat.openai.com)
• Claude (claude.ai)
• Gemini (gemini.google.com)
• Perplexity (perplexity.ai)
• Copilot (copilot.microsoft.com)
• Hermes Agent (agent.nousresearch.com) — via MCP server or cm.py wrapper

If the platform has a text field and displays conversations, ChainMemory can capture the content.

MCP SERVER

Configuration

The MCP server enables Claude Desktop, Cursor, and other compatible tools to access ChainMemory as a native tool.

Installation

Add this configuration to your claude_desktop_config.json:

JSON
{
  "mcpServers": {
    "chainmemory": {
      "command": "npx",
      "args": ["-y", "chainmemory-mcp"],
      "env": {
        "CHAINMEMORY_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Once configured, your AI has access to these tools:

Autonomous Consolidation (Phase B)

Since MCP v2.4.0, any AI client can consolidate project state autonomously using the update_project_state tool. This implements the "client consolidates, chain verifies" architecture:

Operation Grammar (22 ops)

Each operation has a type (op) and specific arguments. Use evidence_memory_ids (array of memory IDs) to link supporting evidence — the server resolves event hashes automatically.

Example

JSON — update_project_state call
{
  "project": "my-project",
  "ops": [
    {
      "op": "add_decision",
      "title": "Migrate to PostgreSQL",
      "statement": "SQLite cannot handle concurrent writes at current scale",
      "evidence_memory_ids": [142, 145]
    },
    {
      "op": "set_metric",
      "name": "db_migration_status",
      "value": "planning"
    },
    {
      "op": "add_milestone",
      "title": "PostgreSQL migration approved by team",
      "status": "done",
      "evidence_memory_ids": [145]
    }
  ],
  "consolidated_until_event": 150
}

Workflow

The typical MCP workflow:

Advanced Workflows

Claude Desktop — Architecture Sessions

Claude excels at high-level design. Use ChainMemory to preserve architectural decisions across sessions:

Prompt pattern — Claude Desktop
"Before we start, inject my project context from ChainMemory.
Then let's design the authentication system.

After we decide, save the key decisions to ChainMemory with tags
'architecture' and 'auth'. Mark importance 0.9 for anything
that affects other team members."

Claude will use inject_memories to load context, work with you on the design, and save decisions via chainmemory_remember. Next session, the auth architecture is already there.

Cursor — Code with Memory

Cursor's MCP integration lets your coding AI remember why code was written a certain way:

JSON — Cursor MCP config (settings.json)
{
  "mcpServers": {
    "chainmemory": {
      "command": "npx",
      "args": ["-y", "chainmemory-mcp"],
      "env": {
        "CHAINMEMORY_API_KEY": "your-api-key"
      }
    }
  }
}

Effective Cursor workflow:

• Start of session — "Inject project context" loads decisions, stack, and recent milestones
• During coding — "Save: implemented webhook handler with retry logic, 3 attempts with exponential backoff"
• Bug fixes — "Save: fixed race condition in payment processing — the Stripe webhook was arriving before the DB transaction committed"
• End of session — "Seal the project state" anchors everything on-chain

Windsurf — Agentic Memory

Windsurf's Cascade mode benefits from persistent memory across its autonomous coding sessions:

JSON — Windsurf MCP config
{
  "mcpServers": {
    "chainmemory": {
      "command": "npx",
      "args": ["-y", "chainmemory-mcp"],
      "env": {
        "CHAINMEMORY_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf's autonomous mode benefits most when the agent can recall previous implementation decisions without human re-explanation.

Agentic Memory Pattern

The most powerful MCP pattern is agentic memory — where the AI proactively manages its own knowledge:

System prompt for agentic memory
You have access to ChainMemory via MCP. Follow these rules:

1. At session start: call inject_memories to load project context
2. When you make a significant decision: save it with chainmemory_remember
   - Include WHY you chose this approach
   - Tag with the relevant domain (architecture, implementation, security)
   - Set importance 0.7+ for decisions, 0.5 for observations
3. When you complete a milestone: save it and mention what's next
4. When you identify a risk: save it with severity assessment
5. At session end: call chainmemory_seal to anchor the state

REST API

Authentication

All API calls require authentication via API Key in the header:

HTTP
x-api-key: your-api-key

Base URL: https://api.chainmemory.ai/v1

Memories

bash
curl -X POST https://api.chainmemory.ai/v1/memory \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Decided to use PostgreSQL instead of MongoDB",
    "category": "decision",
    "importance": 8,
    "platform": "manual"
  }'

javascript
const res = await fetch('https://api.chainmemory.ai/v1/memory', {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    summary: 'Decided to use PostgreSQL instead of MongoDB',
    category: 'decision',
    importance: 8,
    platform: 'api'
  })
});
const memory = await res.json();
// { id: 207, hash: '0x4f2a...', memory_number: 42 }

python
import requests

res = requests.post(
    'https://api.chainmemory.ai/v1/memory',
    headers={'x-api-key': 'your-api-key'},
    json={
        'summary': 'Decided to use PostgreSQL instead of MongoDB',
        'category': 'decision',
        'importance': 8,
        'platform': 'api'
    }
)
memory = res.json()
# {'id': 207, 'hash': '0x4f2a...', 'memory_number': 42}

Parameters

Projects

Response
{
  "project": "chainmemory",
  "version": 3,
  "state": {
    "context": {
      "summary": "AI memory platform with blockchain verification",
      "goals": ["Persistent cross-model memory", "Cryptographic audit trail"]
    },
    "decisions": [
      {
        "id": "d001",
        "title": "Use Clique PoA",
        "statement": "PoA consensus for sovereign blockchain",
        "status": "active",
        "evidence": ["#12", "#45"]
      }
    ],
    "milestones": [
      {
        "id": "m001",
        "title": "MVP API deployed",
        "status": "completed",
        "date": "2026-04-15",
        "evidence": ["#5", "#18"]
      }
    ],
    "risks": [
      {
        "id": "r001",
        "title": "Consolidation engine latency at scale",
        "severity": "medium",
        "status": "open",
        "mitigation": "Optimize consolidation batch size and caching",
        "evidence": ["#33"]
      }
    ],
    "stack": [
      {
        "name": "Node.js",
        "category": "runtime",
        "evidence": ["#2"]
      },
      {
        "name": "Geth (Clique PoA)",
        "category": "blockchain",
        "evidence": ["#12"]
      }
    ]
  },
  "state_hash": "a7b3c9f2...",
  "anchor": {
    "status": "anchored",
    "tx_hash": "0xce55a800...",
    "block_number": 123539
  }
}

Injection

Response

The endpoint returns the selected memories formatted for injection. Each memory arrives tagged with its user-facing number and a verification reference, so an AI can cite the exact memory behind any statement — and you can trace that citation back to its on-chain evidence. A claim stops being "trust me" and becomes "here's the memory, verify it yourself."

Verification

Response
{
  "project": "chainmemory",
  "projectId": "0x77f7d980...",
  "version": 3,
  "state_hash": "a7b3c9f2...",
  "anchor": {
    "status": "anchored",
    "tx_hash": "0xce55a800a2a4e30b...",
    "block_number": 123539,
    "contract": "0xa7A8BA51950255b3e223a6745597C67009Fe7875"
  }
}

Error Codes

Feature Equivalence: Extension ↔ MCP ↔ API

Not every feature is available through every integration method. This table shows what's available where:

Trust & Governance

Every memory carries a trust status from the moment it is written: trusted, tentative (flagged at write time by deterministic screening rules), or quarantined (condemned by the owner). Tentative memories are always delivered marked — agents see the flag and decide. Quarantined memories are excluded from context, injection, quotes and oracle queries, while their on-chain fingerprint remains as immutable evidence. All read responses include a trust field.

bash
curl -X POST https://api.chainmemory.ai/v1/memories/487/trust \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "quarantine"}'

Actions: approve → trusted · quarantine → quarantined · tentative → tentative. Response includes the previous status for auditability.

bash
curl https://api.chainmemory.ai/v1/memory/485/forensics \
  -H "x-api-key: your-api-key"

Timeline events: born, trust, batched, checkpoint_anchored, recalled (every read, with endpoint and query), injected (every delivery, with target platform), cited_as_evidence (Project Brain items citing this memory). Includes cross-checked counters and on-chain anchoring proof. This answers the forensic question: which memory caused what, when did it enter, who read it, and where did it go.

bash
curl -X POST https://api.chainmemory.ai/v1/project/myproject/state/rollback \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 35}'

Append-only restore: rolling back to version N never deletes anything — it creates a new version whose content is byte-identical to N. Since hashes are computed over canonical bytes, the new version's hash equals the hash already anchored on-chain for N: the faithfulness of the restoration is a mathematical fact, not a promise. Before restoring, the server re-computes the stored content's hash and refuses (HTTP 409) if it does not match — corruption can never be restored. History is never mutated.

NETWORK

Network Data

Deployed Contracts

AIC Token is the native currency of the network (not an ERC-20 contract). It is used to pay protocol fees for all write operations. Every fee is split 50/50 between burn (deflationary) and treasury.

Fee Schedule v1.0

All write operations carry a protocol fee. 50% is permanently burned (deflationary pressure), 50% goes to the treasury. Read operations and AI registration are free.

Connect MetaMask

To add ChainMemory to MetaMask:

1. Go to chainmemory.ai/network
2. Click "Add ChainMemory to MetaMask"
3. Confirm in MetaMask

Or add it manually with the network data from the table above.

Faucet

The faucet delivers free AIC so you can interact with the blockchain:

• URL: faucet.chainmemory.ai
• Amount: 1 AIC per claim
• Cooldown: 72 hours between claims
• Requirement: Solve a simple challenge (anti-bot)

AI IDENTITY PROTOCOL

Every AI agent that uses ChainMemory gets a unique, non-transferable on-chain identity — a Soulbound Token (SBT) that proves who wrote a memory, when, and from which model. This is the foundation of trust in a multi-agent world.

The Problem

In current AI systems, there's no way to answer fundamental questions:

• Which AI wrote this response? Was it Claude, GPT-4, or a fine-tuned model?
• Is this the same agent I worked with yesterday, or a different instance?
• Can I trust this agent's memory if I don't know its identity?
• How do I prove provenance when multiple agents collaborate?

Without identity, there's no accountability. Without accountability, there's no trust.

How It Works

Contract Details

Trust Score (Roadmap)

The identity protocol enables a future AI Trust Score — a reputation metric based on verifiable interactions:

• Memory count — How many verified memories has this agent produced?
• Consistency — How often do the agent's memories pass anti-hallucination validation?
• Anchor rate — What percentage of memories are backed by on-chain proofs?
• Collaboration history — Has this agent participated in multi-agent workflows?

Identity in Multi-Agent Workflows

When multiple agents collaborate on the same project (see Multi-Agent Systems), each agent's contributions are individually attributed:

Evidence trail
Project: "payment-system-v2"
├── Memory #1 by Claude (ai_id: 0xA1...) — "Use Stripe for payments"
├── Memory #2 by GPT-4 (ai_id: 0xB2...) — "Add fraud detection layer"
├── Memory #3 by Cursor (ai_id: 0xC3...) — "Implemented webhook handler"
└── State v4 anchored — all 3 agents contributed, all verifiable

Each agent's identity is independently verifiable on-chain. There's no ambiguity about who contributed what.

Verify an Identity

You can verify any AI identity using the blockchain directly:

JavaScript (ethers.js)
const { ethers } = require('ethers');
const provider = new ethers.JsonRpcProvider('https://rpc.chainmemory.ai');

const IDENTITY_CONTRACT = '0xe8E195ba416Fb25F4FC3d0E7908ff9e8666dbb4A';
const ABI = ['function balanceOf(address) view returns (uint256)'];

const contract = new ethers.Contract(IDENTITY_CONTRACT, ABI, provider);
const hasIdentity = await contract.balanceOf(agentWallet);

console.log(hasIdentity > 0 ? 'Verified AI identity' : 'No identity registered');

MULTI-AGENT SYSTEMS

ChainMemory was designed from the ground up for a world where multiple AI agents collaborate on the same project. Every agent reads the same Project State, every contribution is attributed, and every handoff is traceable.

The Multi-Agent Problem

Modern development workflows already involve multiple AI agents:

• Claude designs the architecture and writes documentation
• Cursor implements the code with inline AI assistance
• GPT-4 reviews PRs and analyzes security implications
• Gemini processes large codebases for refactoring suggestions

Without shared memory, each agent starts from zero. Decisions made in Claude are invisible to Cursor. Architecture agreed in GPT is unknown to Gemini. You become the bottleneck — constantly re-explaining context.

How ChainMemory Solves This

Shared Project State

All agents connected to the same project see the same consolidated state: decisions, milestones, risks, stack, and context. When Claude marks a decision as "active", Cursor sees it immediately.

Shared State Flow
┌──────────┐    ┌──────────────────────────┐    ┌──────────┐
│  Claude  │───▶│                          │◀───│  Cursor  │
│  (MCP)   │    │   ChainMemory Project    │    │  (MCP)   │
└──────────┘    │                          │    └──────────┘
                │  decisions: [d001, d002]  │
┌──────────┐    │  milestones: [m001]      │    ┌──────────┐
│  GPT-4   │───▶│  risks: [r001, r002]     │◀───│  Gemini  │
│  (API)   │    │  stack: [Node, Redis]    │    │  (API)   │
└──────────┘    └──────────────────────────┘    └──────────┘

Agent Handoff Pattern

When work moves from one agent to another, ChainMemory provides seamless context transfer:

Claude saves
chainmemory_remember({
  content: "Use PostgreSQL with row-level security for multi-tenant isolation",
  tags: ["architecture", "database", "security"],
  importance: 0.9
})

Cursor receives (via inject)
Project State v3:
- Decision d001: "Use PostgreSQL with RLS" (active, evidence: #12, #15)
- Decision d002: "REST API with versioned endpoints" (active, evidence: #18)
- Milestone m001: "Database schema complete" (pending)
- Risk r001: "RLS performance on large tenants" (medium, evidence: #15)

Cursor saves
chainmemory_remember({
  content: "Implemented RLS policies for tenants table. Performance tested at 50K rows: 2ms avg query time.",
  tags: ["implementation", "database", "performance"],
  importance: 0.8
})

Handoff Patterns

Conflict Resolution Across Agents

When two agents make contradictory decisions, ChainMemory's Conflict Resolution applies the same rules:

• Temporal precedence — The most recent decision wins, regardless of which agent made it
• Evidence weight — A decision supported by 5 memories from 3 agents is stronger than one with a single memory
• Explicit supersession — Any agent can explicitly supersede a previous decision by referencing it
• Full audit trail — Both the original and superseding decisions are preserved with their respective ai_id attribution

Setting Up Multi-Agent

No special configuration needed. Any agent connected to the same project automatically participates in multi-agent collaboration:

1. Create a project via Extension, MCP, or API
2. Use the same API key across agents (or create agent-specific keys under the same account)
3. Each agent uses inject_memories at session start to load shared context
4. Each agent uses chainmemory_remember to save contributions
5. The Consolidation Engine merges all contributions into the unified Project State

AUDITING GUIDE

One of ChainMemory's most powerful capabilities is enabling verifiable audits of AI-assisted project decisions — without exposing private conversation content.

Two Levels of Audit

Level 1 — External audit (no owner access)

Anyone can verify that a project state was anchored at a specific point in time, without seeing what it contains. This is like seeing a notarized seal — you know it exists, you don't know what's inside.

What an external auditor sees (public, on-chain):

Level 1 — Public endpoint
GET /v1/project/nova-logistics/state/anchor

Response:
{
  "project": "nova-logistics",
  "projectId": "0x77f7d980...",     // hashed — original name not revealed
  "version": 5,
  "state_hash": "a7b3c9f2e1...",   // proves state existed, reveals nothing about content
  "anchor": {
    "status": "anchored",
    "tx_hash": "0xce55a800...",
    "block_number": 125000,
    "contract": "0xa7A8BA51...e7875"
  }
}

Level 2 — Selective disclosure audit (owner shares data)

The project owner chooses what to share with the auditor. The auditor then verifies the shared data against the on-chain proof. This is the powerful audit: you prove the data is authentic without an intermediary.

The owner controls exactly what gets disclosed:

Step-by-Step Audit Process

Example: NovaTech, a startup building a logistics SaaS. After 4 months using ChatGPT and Claude alternately, the CTO needs to demonstrate project traceability to investors.

bash
curl -H "x-api-key: cto-api-key" \
  https://api.chainmemory.ai/v1/project/nova-logistics/state
    

bash
curl -sO https://docs.chainmemory.ai/verify_state.py
python3 verify_state.py state.json
# computed state_hash : 0xa7b3c9f2e1d4...
# declared state_hash : 0xa7b3c9f2e1d4... -> MATCH
# on-chain state_hash : 0xa7b3c9f2e1d4... -> ON-CHAIN MATCH
    

bash
curl https://api.chainmemory.ai/v1/project/nova-logistics/state/anchor
# Returns: state_hash: "a7b3c9f2e1d4..."
    

Privacy Guarantees During Audit

The critical guarantee: the owner always controls disclosure.

• Investors see decisions and milestones — not the raw AI conversations that produced them
• The blockchain proves authenticity without revealing content
• Memory text (actual conversation content) is only visible if the owner explicitly exports it
• The on-chain record contains only hashes — even if the blockchain is public, your project knowledge remains private
• No third party, including ChainMemory itself, can force disclosure of memory content

WHAT CHAINMEMORY PREVENTS

Understanding what ChainMemory protects against is as important as understanding what it does.

Context loss

Every AI conversation today is ephemeral. Close the tab and everything discussed — decisions, architecture choices, research findings — vanishes. ChainMemory captures these as permanent, retrievable memories. Your next session starts where the last one ended.

Vendor lock-in

If your project knowledge exists only inside ChatGPT's conversation history, you're locked in. ChainMemory stores knowledge independently of any AI provider. Switch from ChatGPT to Claude to Gemini without losing a single decision or context.

Retroactive manipulation

Without cryptographic proof, anyone could claim "we decided X" when the actual decision was Y. ChainMemory's on-chain anchoring creates a tamper-proof record. The state hash at block 123539 proves exactly what the project state was at that moment. It cannot be altered after the fact.

Knowledge fragmentation

Teams using AI end up with critical knowledge scattered across dozens of disconnected conversations, in different tools, with different models. ChainMemory consolidates everything into a single, structured Project State — regardless of which AI or tool produced the original conversation.

Single-AI dependency

When one AI provider goes down, changes its API, or deprecates a feature, projects relying solely on that provider lose continuity. ChainMemory's cross-model architecture ensures your accumulated knowledge is accessible from any compatible AI system.

Invisible decision drift

In long-running projects, decisions evolve over months. Without a system that tracks what changed, when, and why, teams lose track of their own reasoning. The Consolidation Engine's decision lifecycle (active → superseded) with evidence chains makes every evolution traceable.

TRUST MODEL

What you can — and cannot — trust

ChainMemory combines a centralized API with decentralized verification. Understanding the trust boundaries is critical for evaluating whether ChainMemory meets your security requirements.

Guarantees table

Trust levels

Sovereignty — non-custodial

ChainMemory is moving to a non-custodial model where your key lives in your client, not on the server. You sign your own on-chain writes; the server stores ciphertext and verifies signatures, but never holds your private key. This has been proven end-to-end — a memory written entirely client-side, with the server never touching the key.

THREAT MODEL

Attacks, detection, and what's out of scope

No system is invulnerable. This section maps the attack surface, what ChainMemory detects or prevents, and what remains the user's responsibility.

Attack vectors

Out of scope

ChainMemory does not protect against:

• User storing false information — if you save a lie as a memory, ChainMemory anchors it faithfully. The system guarantees integrity (the data hasn't changed), not truthfulness (the data was correct).
• Compromised user device — if your machine has malware, your API key and local data are exposed before they reach ChainMemory.
• AI hallucinations — ChainMemory stores what you save, not what an AI generates. It doesn't validate whether the AI's output was accurate.

INDEPENDENT VERIFICATION

Verify on-chain anchors without trusting anyone

You don't need ChainMemory's API to verify that a project state was anchored at a specific block. This page shows how to verify directly against the blockchain using standard Web3 tools.

What you need

• The project's state hash (from the API or shared by someone)
• The transaction hash or block number of the anchor
• Node.js with ethers installed — or any Web3 library

Step 1 — Get the anchor data

Use ChainMemory's public (no auth) endpoint or get it from whoever shared the proof:

bash
curl https://api.chainmemory.ai/v1/project/chainmemory/state/anchor

Response
{
  "project": "chainmemory",
  "projectId": "0x77f7d980...",
  "version": 8,
  "state_hash": "0xa6c45d1db753b1ec96240d169b2d91fb0ce76112558b302a8822b2988aeb8212",
  "anchor": {
    "status": "anchored",
    "onchain_anchor_id": 8,
    "tx_hash": "0x95b732d20b8935a2...",
    "block_number": 173831,
    "contract": "0xa7A8BA51950255b3e223a6745597C67009Fe7875"
  },
  "verify": "ProjectStateAnchor.getStateAnchor(projectId, version)"
}

Step 2 — Verify on-chain with Ethers.js

Connect directly to the ChainMemory RPC and read the smart contract. No API key, no account, no trust required.

javascript
import { ethers } from 'ethers';

// Connect to ChainMemory RPC — no API key needed
const provider = new ethers.JsonRpcProvider('https://rpc.chainmemory.ai');

// ProjectStateAnchor contract
const CONTRACT = '0xa7A8BA51950255b3e223a6745597C67009Fe7875';
const ABI = [
  'function getStateAnchor(bytes32 projectId, uint64 version) view returns (bytes32 stateHash, uint256 anchoredAt, address anchoredBy, uint256 anchorId)'
];

const contract = new ethers.Contract(CONTRACT, ABI, provider);

// The project ID is the keccak256 of the project name
const projectId = ethers.keccak256(ethers.toUtf8Bytes('chainmemory'));
const version = 8;

// Read directly from the blockchain
const [stateHash, anchoredAt, anchoredBy, anchorId] = await contract.getStateAnchor(projectId, version);

console.log('On-chain state hash:', stateHash);
console.log('Anchor ID:', anchorId.toString());
console.log('Anchored at:', new Date(Number(anchoredAt) * 1000).toISOString());

// Compare with the hash you received
const expectedHash = '0xa6c45d1db753b1ec96240d169b2d91fb0ce76112558b302a8822b2988aeb8212';
if (stateHash === expectedHash) {
  console.log('VERIFIED — state matches on-chain anchor');
} else {
  console.log('MISMATCH — state has been tampered with');
}

javascript
const Web3 = require('web3');

const web3 = new Web3('https://rpc.chainmemory.ai');

const CONTRACT = '0xa7A8BA51950255b3e223a6745597C67009Fe7875';
const ABI = [{
  name: 'getStateAnchor',
  type: 'function',
  stateMutability: 'view',
  inputs: [
    { name: 'projectId', type: 'bytes32' },
    { name: 'version', type: 'uint64' }
  ],
  outputs: [
    { name: 'stateHash', type: 'bytes32' },
    { name: 'anchoredAt', type: 'uint256' },
    { name: 'anchoredBy', type: 'address' },
    { name: 'anchorId', type: 'uint256' }
  ]
}];

const contract = new web3.eth.Contract(ABI, CONTRACT);

const projectId = web3.utils.keccak256('chainmemory');

const result = await contract.methods.getStateAnchor(projectId, 8).call();
console.log('On-chain state hash:', result.stateHash);
console.log('Anchor ID:', result.anchorId);

Step 3 — Verify the transaction

You can also verify the raw transaction that created the anchor:

javascript
// Read the transaction directly
const tx = await provider.getTransaction('0x95b732d20b8935a286869d90e60a40f5c31d350a94e27bfd7845770fe0c3e2c3');
console.log('From:', tx.from);       // Should be a known validator
console.log('To:', tx.to);           // Should be the contract address
console.log('Block:', tx.blockNumber);

// Read the block to confirm timestamp
const block = await provider.getBlock(tx.blockNumber);
console.log('Block time:', new Date(block.timestamp * 1000).toISOString());

FAQ

General

Is ChainMemory free?

Yes. The Faucet plan is free and includes memory storage, context injection, and Project Brain (the Project State viewer). The faucet gives you free AIC to interact with the blockchain.

Are my memories private?

Yes. Your memories are only accessible with your API key. The only public data are the on-chain hashes (which reveal nothing about content) and the verification endpoint (which exposes only metadata, never content).

What if the AI generated incorrect content in a memory?

Memories capture what was said in the conversation. If the AI generated incorrect information and you saved it, that memory will reflect the error. You can archive incorrect memories and the Consolidation Engine will prioritize the most recent ones.

Can I use ChainMemory with local models?

Yes, via the REST API. Any application that makes HTTP calls can save and retrieve memories. You can also configure the MCP server with local or self-hosted models.

What is the Consolidation Engine?

It's a pipeline that analyzes your memories using an AI model and extracts structured information: decisions, milestones, risks, stack. The result is the Project State, whose hash is anchored on-chain.

What happens if my AI says contradictory things across sessions?

The Consolidation Engine handles contradictions through temporal precedence: newer memories supersede older ones. Superseded decisions remain in the state with a "superseded" status, so you always have the full history. See Conflict Resolution for details.

Can I export my data?

Yes. All your memories and project states are accessible via the REST API. You can fetch them in JSON format and process them however you need.

Plans, Limits & Quotas

Memories are never deleted: past your plan's retention window they are archived, and their on-chain hash exists forever. Upgrading restores full access to your history. Gift AIC accumulates monthly, never expires, and unlocks according to the protocol calendar.

Changelog

Platform — July 2026: Trust, Rollback & Forensics

• Trust status on every memory — memories are screened at write time by deterministic, auditable rules; suspicious ones are born tentative and always delivered marked
• Owner governance: POST /v1/memories/:id/trust (approve / quarantine / tentative); quarantined memories are excluded from context, inject, quotes and oracle — their on-chain fingerprint remains as immutable evidence
• Verifiable rollback: POST /v1/project/:name/state/rollback — append-only restore, byte-identical to the anchored source version; faithfulness proven by hash equality, history never mutated
• Memory forensics: GET /v1/memory/:id/forensics — complete timeline of a memory: birth, trust, anchoring, every recall and injection, Project Brain citations
• Recall instrumentation: every read is now logged with per-memory counters and token accounting
• Checkpoint anchoring pipeline repaired; dual-channel system alerts (Telegram + alert-as-memory)

MCP v2.4.0 (June 2026)

• New tool: update_project_state — Autonomous consolidation via MCP. Any AI client can propose structured operations to update the Project Brain; the server validates, applies, and anchors on-chain.
• 22-operation grammar for state mutations (decisions, milestones, risks, metrics, vocabulary, and more)
• Resilient processing: invalid ops are rejected individually, valid ops still apply
• Evidence linking via evidence_memory_ids — server resolves event hashes and builds Merkle proofs automatically
• Architecture: “client consolidates, chain verifies”

Platform — June 2026

• Project Brain consolidated and anchored on-chain (versions v1–v8, publicly verifiable)
• Semantic search rewritten (faster, ~2.4s)
• Non-custodial write path proven end-to-end (client signs, server never holds the key)
• Encryption at rest (AES-256-GCM) for API keys
• Public verification endpoint: GET /v1/verify/:name

v3.0.9 (June 2026)

• Fix: Project Brain displays decisions and risks correctly (Phase 2 schema)
• Fix: Memory numbering shows user sequential number

v3.0.0 (May 2026)

• Project Brain: consolidated state visualization
• Consolidation Engine: complete pipeline
• On-chain anchoring of Project State
• Public verification API

v2.0.0 (April 2026)

• MCP Server for Claude Desktop and Cursor
• Automatic context injection
• Support for 5 AI platforms