# ChainMemory Documentation (Full Content)

> Complete technical documentation for ChainMemory — the dedicated public blockchain (Chain ID 202604) for AI memory.
> This file contains the full documentation content for consumption by LLMs and AI agents.
> Language: English
> Generated: 2026-06-11

---

# 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.

**The core insight**
Memories are events. The Project State is a materialized view. The blockchain is the timestamp authority. Together, they form a system where AI knowledge is persistent, portable, structured, and provably authentic.

---

## 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.

**Three access methods**
Chrome Extension (one click from any chat), MCP Server (native integration with Claude/Cursor), and REST API (full control from your code).

---

## 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

  
    | Scenario | Without ChainMemory | With ChainMemory |

  
  
    
      | You spend 2 hours with Claude designing a database schema 
      | Close the tab. Next session, Claude has zero memory of the schema. You re-explain everything from scratch. 
      | The decision is saved as a memory. Next session, Claude receives the schema automatically via context injection. 
    |

    
      | Your team switches from ChatGPT to Gemini mid-project 
      | All conversation history stays locked in ChatGPT. Gemini starts with nothing. Weeks of context lost. 
      | Gemini receives the full Project State — decisions, risks, milestones, stack — as if it had been there from day one. 
    |

    
      | A stakeholder asks "when did we decide to use PostgreSQL?" 
      | You search through hundreds of chat threads hoping to find it. Maybe it was in Slack? Maybe a different AI? 
      | The decision has a hash, a timestamp, and evidence links. You share the verification URL — cryptographic proof. 
    |

    
      | Two team members make conflicting architecture decisions using different AIs 
      | Nobody notices until production breaks. No audit trail showing who decided what. 
      | The Consolidation Engine detects the conflict, flags it, and tracks which decision supersedes the other. 
    |

    
      | An auditor asks for proof that a compliance decision was made before the deadline 
      | You have screenshots and "trust me." No tamper-proof evidence. 
      | The state was anchored on-chain at block N. The hash is immutable. The auditor verifies independently. 
    |

  

### 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.

**The 5-minute test**
Install the extension, save one memory, switch to a different AI, and inject the context. You'll see your decision arrive intact in under 5 minutes. That's the moment it clicks.

---

## QUICKSTART

Store → Retrieve → Verify → Prove in 5 minutes

### Prerequisites

  - Google Chrome (or any Chromium browser)

  - A ChainMemory account — [create one here](#account-create)

  - Your API Key (from the Extension settings or dashboard)

### Option A — Chrome Extension (fastest)

  1
  
    
#### Install & sign in

    Download from the [Chrome Web Store](https://chromewebstore.google.com/detail/chainmemory). Sign in with your account. The extension icon appears in your toolbar.

  

  2
  
    
#### Store — save a memory

    Open any AI chat (ChatGPT, Claude, Gemini). Have a conversation where you make a decision — e.g., "We'll use PostgreSQL for the user database." Click the ChainMemory icon and save. The extension extracts the content and creates a memory linked to your project.

  

  3
  
    
#### Retrieve — inject into a new session

    Open a **different** AI (or a new conversation in the same one). Click the ChainMemory icon → "Inject Context." Your previous decision arrives automatically — the AI now knows about the PostgreSQL choice without you repeating anything.

  

  4
  
    
#### Verify — check the hash

    In the Extension, open Project Brain. You'll see your project state with decisions, hashes, and evidence links. Each state has a SHA-256 hash computed from all its memories.

  

  5
  
    
#### Prove — anchor on-chain

    Click "Seal" to anchor the current state hash on the blockchain. Once confirmed, the state is immutable — anyone can verify it was recorded at that exact block and time.

  

**Result**
You've stored a decision, retrieved it in a different AI, verified its hash, and created an immutable on-chain proof. All in under 5 minutes.

### Option B — MCP Server (for Claude / Cursor)

  1
  
    
#### Configure MCP

    Add the ChainMemory MCP server to your Claude Desktop or Cursor configuration. See [MCP Setup](#mcp-setup) for the full config.

  

  2
  
    
#### Store

    In Claude, say: `"Remember: we decided to use PostgreSQL for the user database"`. The MCP tool `chainmemory_remember` fires automatically.

  

  3
  
    
#### Retrieve

    In a new conversation: `"What database did we choose?"`. Claude calls `chainmemory_recall` and returns the stored decision with its evidence chain.

  

  4
  
    
#### Verify & Prove

    Say: `"Seal the current project state"`. The tool `chainmemory_seal` anchors the hash on-chain and returns the transaction hash.

  

### Option C — REST API (full control)

bash
# 1. Store a memory
curl -X POST https://api.chainmemory.ai/v1/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Decided to use PostgreSQL for user DB","project":"my-project","tags":["decision"]}'

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

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

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

**What's next**
Explore [how event sourcing works](#concept-event-sourcing), learn about the [trust model](#trust-model), or dive into the [full API reference](#api-auth).

---

## 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.

  1
  
    
#### Install the Extension

    Download from the [Chrome Web Store](https://chromewebstore.google.com/detail/chainmemory) and click "Add to Chrome".

  

  2
  
    
#### Create Account

    Click the ChainMemory icon in your browser toolbar. Choose "Create Account" and enter your email and password. Your account is created instantly.

  

  3
  
    
#### Get Your API Key

    After signing in, go to Settings inside the extension popup. Your API Key is displayed there. Copy it — you'll need it for MCP and API access.

  

**Keep your API Key safe**
Your API Key grants full access to your memories and projects. Never share it in public repositories or frontend code. Store it in environment variables or a secrets manager.

### Create Your First Project

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

  1
  
    
#### Via the Extension

    In the extension popup, click "New Project". Enter a slug (lowercase, no spaces — e.g., `my-saas`, `thesis-ml`) and an optional description. Click Create.

  

  2
  
    
#### Via the API

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

  3
  
    
#### Via MCP

    If you have the MCP server configured, ask your AI: *"Create a new ChainMemory project called my-saas"*. The AI will use the `create_project` tool automatically.

  

**Project naming**
Choose descriptive, short slugs. You'll reference them in every API call and MCP interaction. Examples: `chainmemory`, `mobile-app`, `data-pipeline`.

### Credentials Summary

  | Credential | Where to Find | Used For |

  
    | Email + Password | Set during sign-up | Extension login |

    | API Key | Extension → Settings | REST API calls, MCP server config |

    | Project slug | Extension → Projects | All memory operations (save, recall, inject, seal) |

  

**Get free AIC tokens**
Visit [faucet.chainmemory.ai](https://faucet.chainmemory.ai) to claim 1 AIC. You'll need AIC to anchor your Project State on-chain. 1 AIC is enough for hundreds of anchor operations.

---

## 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 with a local LLM 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 (phi3:mini via Ollama)
      |
  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

  
    
      | Feature 
      | ChainMemory 
      | Mem0 
      | Zep / Graphiti 
      | Cognee 
      | Supermemory 
      | Letta 
    |

  
  
    
      | **Storage model** 
      | Episodic DB + on-chain anchoring 
      | Vector + Graph (hybrid) 
      | Temporal knowledge graph (Neo4j) 
      | Graph + Vector + Relational (poly-store) 
      | Semantic vectors + temporal traces 
      | Hierarchical (core + external) 
    |

    
      | **Cryptographic verification** 
      | ✓ Sovereign blockchain 
      | ✗ Centralized 
      | ✗ Centralized 
      | ✗ Centralized 
      | ✗ Local only 
      | ✗ None 
    |

    
      | **On-chain proof** 
      | ✓ Merkle roots + tx hash 
      | ✗ 
      | ✗ 
      | ✗ 
      | ✗ 
      | ✗ 
    |

    
      | **Cross-model portability** 
      | ✓ Extension + MCP + API 
      | ~ API + MCP 
      | ~ API + MCP 
      | ~ Python SDK 
      | ~ MCP + API 
      | ✗ Tied to framework 
    |

    
      | **Structured consolidation** 
      | ✓ 6-category engine (decisions, milestones, risks, stack...) 
      | ✗ Raw facts 
      | ~ Knowledge graph relationships 
      | ~ Pipeline enrichment 
      | ✗ Semantic traces 
      | ~ Manual summarization 
    |

    
      | **Temporal awareness** 
      | ✓ Version chain + on-chain timestamps 
      | ~ Basic 
      | ✓ Fact validity windows 
      | ~ Added 2025 
      | ~ Time-annotated traces 
      | ✗ 
    |

    
      | **Decision audit trail** 
      | ✓ Evidence chain with memory refs 
      | ✗ 
      | ~ Provenance tracking 
      | ✗ 
      | ✗ 
      | ✗ 
    |

    
      | **Non-developer access** 
      | ✓ Chrome extension (1-click save) 
      | ✗ Developer-only 
      | ✗ Developer-only 
      | ✗ Developer-only 
      | ~ Browser extension 
      | ✗ Developer-only 
    |

    
      | **AI identity / attribution** 
      | ✓ Soulbound Tokens (EIP-5192) 
      | ✗ 
      | ✗ 
      | ✗ 
      | ✗ 
      | ✗ 
    |

    
      | **Privacy model** 
      | ✓ Content never on-chain, only hashes 
      | ~ Cloud storage (SOC2) 
      | ~ Enterprise: BYOK/BYOM 
      | ✓ Self-hosted 
      | ✓ Fully local 
      | ~ Self-hosted option 
    |

    
      | **Open source** 
      | ✓ Fully open 
      | ~ OpenMemory (local only) 
      | ✓ Graphiti (20K+ stars) 
      | ✓ Core engine 
      | ✓ Full stack 
      | ✓ Core 
    |

    
      | **Best for** 
      | Audit, compliance, multi-agent traceability 
      | Rapid prototyping, user personalization 
      | Complex agent reasoning, CRM workflows 
      | Enterprise data pipelines, RAG enhancement 
      | Coding agents, local-first memory 
      | Research, long-lived agents 
    |

  

### 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 with Ollama, 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.

**Key differentiator**
ChainMemory is the only solution that combines three capabilities no other tool has together: (1) **structured knowledge extraction** (6-category consolidation engine, not just raw storage), (2) **cross-model portability** (Extension + MCP + API, not tied to any framework), and (3) **cryptographic verification** (sovereign blockchain with Merkle proofs, not trust-based). Other tools store memories. ChainMemory builds **verifiable project knowledge**.

**Not mutually exclusive**
ChainMemory can complement other memory tools. Use Supermemory or Mem0 for fast in-session recall, and ChainMemory for permanent, auditable project decisions. The structured Project State from ChainMemory can feed into a knowledge graph like Graphiti for richer reasoning.

---

## 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.

**Why this matters**
Event-sourcing guarantees full traceability. Every decision in your Project State can be traced back to the specific conversation where it originated. Nothing is lost, nothing is overwritten, and the history is always available.

### 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](#concept-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**: a local LLM (phi3:mini via Ollama) 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

  | Category | What it captures | Example |

  
    | **context** | Summary, goals, and scope of the project | "E-commerce platform for artisan goods, targeting 10K users by Q3" |

    | **decisions** | Architectural and strategic choices with status (active/superseded/evaluating) | "Use Stripe for payments" (active, evidence: #12, #45) |

    | **milestones** | Deliverables and checkpoints (completed/pending) with dates | "Database schema complete" (completed, 2026-05-15) |

    | **risks** | Identified threats with severity (low/medium/high/critical) | "RLS performance at scale" (medium, evidence: #15) |

    | **stack** | Technologies, frameworks, tools, and infrastructure | {name: "PostgreSQL", role: "primary-db", version: "16"} |

    | **dependencies** | External services, APIs, and team relationships | {name: "Stripe API", type: "payment-provider", critical: true} |

  

#### 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

**Tags vs. categories**
Memory tags (set via API/Extension/MCP) are free-form — you can use any label. The 6 categories above belong to the Consolidation Engine, which semantically analyzes memory content to classify it automatically. A memory tagged `"bug"` might contribute to the `risks` category; one tagged `"architecture"` might feed into `decisions` and `stack`. Tags help *you* organize; categories help the *engine* structure.

**Multi-agent state**
When multiple agents contribute to the same project, the Consolidation Engine merges all contributions into a single unified state. Each entry's evidence array shows which agent contributed it via memory attribution. See [Multi-Agent Systems](#multiagent) for details.

### 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**.

**Reconstructing a decision**
To verify any decision: (1) fetch the Project State, (2) look at the evidence array, (3) retrieve each referenced memory, (4) verify hashes match, (5) check the on-chain anchor. The entire chain is independently verifiable.

### 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.

**No data loss**
Superseded decisions are never deleted. They remain in the Project State with their status changed, preserving the full history of how the project's direction evolved. You can always see what was decided before and why it changed.

### 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`.

  | Action | Who | When | Reversible |

  
    | Consolidate | Project owner | Manual or auto (every N memories) | New version created (append-only) |

    | Anchor on-chain | Project owner | After consolidation | Immutable once anchored |

    | Archive memory | Project owner | Anytime | Can unarchive |

    | View any version | Anyone (public endpoint) | Anytime | N/A (read-only) |

  

### 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:

  - Call `GET /v1/project/:name/state/anchor` (no API key required)

  - Get the `state_hash` and the `tx_hash` of the transaction

  - Verify on the [explorer](https://chainmemory.ai/explorer) that the transaction exists

  - 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:

**Critical principle**
Memory content NEVER goes on-chain. Only cryptographic hashes are published to the blockchain.

#### What is stored where

  | Data | Location | Access |

  
    | Memory content (full text) | Encrypted database (off-chain) | Owner only (API key required) |

    | Memory hash (SHA-256) | Database + optionally on-chain | Hash is public but reveals nothing about content |

    | Project State (structured) | Database (off-chain) | Owner only |

    | State hash | Blockchain (on-chain) | Public — this is the verifiable proof |

    | Anchor metadata (tx, block) | Blockchain (on-chain) | Public |

  

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

  - Go to the [Chrome Web Store](https://chromewebstore.google.com/detail/chainmemory)

  - Click "Add to Chrome"

  - The ChainMemory icon appears in the extensions bar

  - Click the icon and create your account or sign in

  - Select or create a project

**Current version**
v3.0.9 — Includes Project Brain (Project State viewer), context injection, and support for 5+ platforms.

### 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.

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

  - Open a new chat on any supported platform

  - The extension detects the text field

  - Select the memories or project state to inject

  - 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)

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"
      }
    }
  }
}

**Get your API Key**
Sign in to the Chrome extension, go to Settings, and copy your API Key. Or request one from your account panel at faucet.chainmemory.ai.

### Available Tools

Once configured, your AI has access to these tools:

  TOOL
  chainmemory_remember
  Save a new memory linked to a project with tags and metadata.

  TOOL
  chainmemory_recall
  Search memories by content, tags, project, or date range.

  TOOL
  chainmemory_stats
  Account statistics: total memories, projects, usage.

  TOOL
  chainmemory_profile
  Profile information and account settings.

  TOOL
  chainmemory_seal
  Anchor the current project state on the blockchain.

  TOOL
  get_project_state
  Get the complete project state: decisions, milestones, stack, and context.

  TOOL
  inject_memories
  Inject relevant memories into the current conversation context.

### Workflow

The typical MCP workflow:

  1
  
    
#### Session start

    When you open Claude Desktop with ChainMemory configured, the project context is injected automatically. Your AI already knows what you're working on.

  

  2
  
    
#### Normal work

    Work with your AI as usual. When something important happens (a decision, a discovery, an architecture change), the AI can automatically save the memory using `chainmemory_remember`.

  

  3
  
    
#### Continuity

    In the next session, `inject_memories` brings the relevant context. You lose nothing between sessions.

  

### 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

**Cross-tool handoff**
The same ChainMemory project works across Claude, Cursor, Windsurf, and any MCP-compatible tool. Design in Claude, implement in Cursor, review in another tool — all sharing the same persistent memory. See [Multi-Agent Systems](#multiagent) for details.

---

## REST API

### Authentication

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

HTTP
Authorization: Bearer your-api-key

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

**Security**
Never expose your API Key in frontend code or public repositories. Use it only in backend or in environment variables.

### Memories

  POST
  /v1/memories
  Create a new memory.

  curl
  JavaScript
  Python

bash
curl -X POST https://api.chainmemory.ai/v1/memories \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Decided to use PostgreSQL instead of MongoDB",
    "project": "my-project",
    "tags": ["decision", "architecture"],
    "source": "manual"
  }'

javascript
const res = await fetch('https://api.chainmemory.ai/v1/memories', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'Decided to use PostgreSQL instead of MongoDB',
    project: 'my-project',
    tags: ['decision', 'architecture'],
    source: 'api'
  })
});
const memory = await res.json();
// { id: 207, hash: '0x4f2a...', memory_number: 42 }

python
import requests

res = requests.post(
    'https://api.chainmemory.ai/v1/memories',
    headers={'Authorization': 'Bearer your-api-key'},
    json={
        'content': 'Decided to use PostgreSQL instead of MongoDB',
        'project': 'my-project',
        'tags': ['decision', 'architecture'],
        'source': 'api'
    }
)
memory = res.json()
# {'id': 207, 'hash': '0x4f2a...', 'memory_number': 42}

#### Parameters

  | Parameter | Type | Description |

  
    | content* | string | Memory content |

    | project* | string | Target project ID |

    | tags | string[] | Tags for organization |

    | source | string | Origin: manual, extension, mcp, api |

  

  GET
  /v1/memories/list
  List memories with optional filters.

  | Parameter | Type | Description |

  
    | project | string | Filter by project |

    | tags | string | Filter by tags (comma-separated) |

    | search | string | Search in content |

    | limit | number | Maximum results (default: 20) |

    | offset | number | Pagination offset |

  

  GET
  /v1/memories/search
  Semantic search by content, tags, project, or date range.

### Projects

  GET
  /v1/projects
  List all user projects.

  GET
  /v1/project/:name/state
  Get the consolidated project state (decisions, milestones, risks, stack).

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": "Ollama model size limits",
        "severity": "medium",
        "status": "open",
        "mitigation": "Evaluate larger models when infra scales",
        "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

  POST
  /v1/memories/inject
  Get relevant memories formatted for prompt injection.

  | Parameter | Type | Description |

  
    | project* | string | Project to inject from |

    | limit | number | Number of memories (default: 10) |

    | include_state | boolean | Include consolidated Project State |

  

### Verification

  GET
  /v1/project/:name/state/anchor
  Verify the on-chain anchor of a project state. Public endpoint, no authentication required.

  | Parameter | Type | Description |

  
    | version | number | Specific version (default: latest) |

  

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

**Independent verification**
Anyone can verify the state by calling this endpoint and comparing the `state_hash` with the one recorded in the on-chain contract. No account or API key needed.

### Error Codes

  | Code | Meaning | Solution |

  
    | 401 | Invalid or missing API Key | Check your Authorization header |

    | 403 | No permissions for this resource | Verify that the project belongs to you |

    | 404 | Resource not found | Check the project name or ID |

    | 429 | Rate limit exceeded | Wait and retry. Limit: 30 req/min (Faucet) or 120 req/min (Pro) |

    | 500 | Internal error | Retry. If persistent, contact support |

  

### Feature Equivalence: Extension ↔ MCP ↔ API

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

  | Feature | Extension | MCP | API REST |

  
    | Save memory | ✓ 1-click save | ✓ chainmemory_remember | ✓ POST /v1/memories |

    | Recall memories | ✓ Memory list | ✓ chainmemory_recall | ✓ GET /v1/memories/list |

    | Search memories | ~ Basic filter | ✓ chainmemory_recall | ✓ GET /v1/memories/search |

    | Inject context | ✓ Auto-inject | ✓ inject_memories | ✓ POST /v1/memories/inject |

    | View Project State | ✓ Project Brain | ✓ get_project_state | ✓ GET /v1/project/:name/state |

    | Seal (anchor on-chain) | ✓ Seal button | ✓ chainmemory_seal | ✗ Not yet available |

    | Account stats | ✓ Dashboard | ✓ chainmemory_stats | ✗ Not yet available |

    | Profile info | ✓ Settings | ✓ chainmemory_profile | ✗ Not yet available |

    | List projects | ✓ Project selector | ✓ list_projects | ✓ GET /v1/projects |

    | Create project | ✓ New Project | ✓ create_project | ✓ POST /v1/projects |

    | Verify anchor | ~ Via Explorer link | ✗ | ✓ GET /v1/project/:name/state/anchor |

    | Archive memory | ✓ | ✓ archive_memory | ✗ Not yet available |

    | Update tags | ✓ | ✓ update_memory_tags | ✗ Not yet available |

  

**API parity roadmap**
Features marked ✗ in the API column are planned for future releases. The MCP server and Extension currently have the most complete feature sets.

---

## NETWORK

### Network Data

  | Field | Value |

  
    | Network | ChainMemory |

    | Chain ID | 202604 |

    | RPC URL | https://rpc.chainmemory.ai |

    | Currency | AIC (native) |

    | Decimals | 18 |

    | Block time | ~15 seconds |

    | Consensus | Clique PoA (3 active signers) |

    | Explorer | [chainmemory.ai/explorer](https://chainmemory.ai/explorer) |

  

### Deployed Contracts

  | Contract | Address | Purpose |

  
    
      | ProjectStateAnchor 
      | `0xa7A8BA51...e7875` 
      | Anchors project state hashes on-chain. Each call records a project ID, version number, and state hash, creating an immutable timestamp proof. 
    |

    
      | AIMemoryRegistry 
      | `0x7a50ed01...30168` 
      | Global registry of AI memory hashes. Allows any memory to be independently verified by checking its SHA-256 hash against the on-chain record. 
    |

    
      | AIIdentityProtocol 
      | `0xe8E195ba...dbb4A` 
      | Identity layer for AI agents. Registers AI instances with their model type, capabilities, and ownership, enabling trust scoring and provenance tracking across interactions. 
    |

  

AIC Token is the native currency of the network (not an ERC-20 contract). It is used to pay for transaction gas when anchoring states and registering memories.

**Gas costs**
A typical `ProjectStateAnchor` transaction costs approximately 0.0005 AIC. At current network conditions, anchoring a project state costs less than a fraction of a cent equivalent. The faucet provides enough AIC for hundreds of anchoring operations.

### Connect MetaMask

To add ChainMemory to MetaMask:

  - Go to [chainmemory.ai/network](https://chainmemory.ai/network)

  - Click "Add ChainMemory to MetaMask"

  - 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](https://faucet.chainmemory.ai)

  - **Amount:** 1 AIC per claim

  - **Cooldown:** 72 hours between claims

  - **Requirement:** Solve a simple challenge (anti-bot)

**Wallet security**
The faucet generates wallets 100% in your browser. Your private key never leaves your device. We recommend downloading the encrypted keystore (JSON) for safekeeping rather than storing the private key as plain text.

---

## 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

  1
  
    
#### Registration

    When a user creates an account or an agent connects via API/MCP, the system registers an identity on-chain via the `AIIdentityProtocol` contract. This creates a Soulbound Token — an NFT that **cannot be transferred**. It's permanently bound to that agent's wallet.

  

  2
  
    
#### Identity Metadata

    Each registered identity stores:

    
      - **Wallet address** — The agent's unique blockchain address

      - **Model type** — claude-sonnet-4, gpt-4o, gemini-2.0, etc.

      - **Capabilities** — What this agent can do (remember, recall, consolidate, seal)

      - **Owner** — The human or organization that controls this agent

      - **Registration block** — Immutable proof of when this identity was created

    
  

  3
  
    
#### Memory Attribution

    Every memory written to ChainMemory includes the `ai_id` of the agent that created it. This means any memory can be traced back to a specific, verified AI identity.

  

### Contract Details

  | Field | Value |

  
    | Contract | AIIdentityProtocol |

    | Address | `0xe8E195ba416Fb25F4FC3d0E7908ff9e8666dbb4A` |

    | Chain | ChainMemory (ID 202604) |

    | Token type | Soulbound (non-transferable ERC-721) |

    | Standard | EIP-5192 (Minimal Soulbound NFTs) |

  

### 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?

**Why Soulbound?**
Regular NFTs can be sold or transferred, which would allow identity spoofing. Soulbound Tokens are permanently bound to the wallet that minted them. An AI agent cannot pretend to be another agent by buying its identity token. This is critical for audit trails — you need to know with certainty which agent wrote which memory.

### Identity in Multi-Agent Workflows

When multiple agents collaborate on the same project (see [Multi-Agent Systems](#multiagent)), 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');

**No identity = no trust**
If an agent doesn't have a registered on-chain identity, its memories cannot be attributed. ChainMemory requires identity registration before allowing memory writes. This ensures every memory in the system has a verifiable author.

---

## 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**:

  1
  
    
#### Claude designs the architecture

    Claude saves key decisions via MCP: database choice, API structure, authentication strategy. Each memory is attributed to Claude's `ai_id`.

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

  2
  
    
#### Cursor picks up implementation

    When you open Cursor, it injects the project context automatically. Cursor knows the database choice, the API structure, and why those decisions were made — without you repeating anything.

    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)
  

  3
  
    
#### Cursor implements and saves progress

    As Cursor implements, it saves implementation memories. These are attributed to Cursor's `ai_id` and feed back into the shared state.

    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
})
  

  4
  
    
#### GPT-4 reviews with full context

    A GPT-4 agent reviewing the PR can query ChainMemory to understand *why* each decision was made, who made it, and what evidence supports it.

  

### Handoff Patterns

  
    
      | Pattern 
      | Flow 
      | Use Case 
    |

  
  
    
      | **Sequential** 
      | Claude → Cursor → GPT-4 
      | Design → Implement → Review 
    |

    
      | **Parallel** 
      | Claude + Cursor + Gemini simultaneously 
      | Multiple developers, same project 
    |

    
      | **Specialist** 
      | Any agent → Security agent → Back 
      | Specific expertise on demand 
    |

    
      | **Supervisory** 
      | Human + Claude oversee, Cursor executes 
      | Human-in-the-loop with delegation 
    |

  

### Conflict Resolution Across Agents

When two agents make contradictory decisions, ChainMemory's [Conflict Resolution](#concept-conflicts) 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

**No single point of truth — except the chain**
In a multi-agent system, no single agent owns the "truth". The Project State is a *materialized view* derived from all agents' contributions. The on-chain anchor is the only authoritative timestamp. This means even if one agent hallucinates or makes an error, the evidence chain allows other agents (or humans) to trace and correct it.

### Setting Up Multi-Agent

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

  - Create a project via Extension, MCP, or API

  - Use the same API key across agents (or create agent-specific keys under the same account)

  - Each agent uses `inject_memories` at session start to load shared context

  - Each agent uses `chainmemory_remember` to save contributions

  - The Consolidation Engine merges all contributions into the unified Project State

**Best practice**
Use descriptive tags that identify the agent's role: `["architecture", "claude-design"]`, `["implementation", "cursor-code"]`, `["review", "gpt4-security"]`. This makes filtering by agent role easy without needing to parse `ai_id` directly.

---

## 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):

  | Data | Visible | Reveals content? |

  
    | state_hash | ✓ Public | No — SHA-256 is irreversible |

    | tx_hash | ✓ Public | No — only proves the transaction happened |

    | block_number | ✓ Public | No — only proves when it was anchored |

    | project ID (hashed) | ✓ Public | No — project name is hashed |

    | version number | ✓ Public | No — only shows how many consolidations occurred |

    | Memory content | ✗ Private | Never on-chain |

    | Decision details | ✗ Private | Never on-chain |

    | Project State | ✗ Private | Never 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"
  }
}

**What this proves**
A project state with hash `a7b3c9f2e1...` was registered at block 125000 on the ChainMemory blockchain. Nothing about the content is revealed. No API key required.

#### 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:

  | Disclosure level | What the auditor sees | Use case |

  
    | State only | Decisions, milestones, risks, stack — no conversation text | Investor due diligence |

    | State + selected memories | Decisions with supporting conversation excerpts | Compliance review |

    | Full export | All memories, full state, complete history | Internal audit, legal discovery |

  

### 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.

  1
  
    
#### Owner exports the Project State

    The CTO calls the API with their key and exports the state JSON:

    bash
curl -H "Authorization: Bearer cto-api-key" \
  https://api.chainmemory.ai/v1/project/nova-logistics/state
    
    Result: 12 active decisions, 3 superseded, 8 completed milestones, 2 open risks. The CTO shares this JSON with the investor.

  

  2
  
    
#### Auditor computes the hash

    The investor takes the received JSON and computes its SHA-256 hash:

    bash
cat state.json | sha256sum
# a7b3c9f2e1d4...
    
  

  3
  
    
#### Auditor verifies against the blockchain

    The investor calls the public verification endpoint (no API key needed):

    bash
curl https://api.chainmemory.ai/v1/project/nova-logistics/state/anchor
# Returns: state_hash: "a7b3c9f2e1d4..."
    
    If the hashes match: the state is **authentic and unmodified** since the anchor date.

  

  4
  
    
#### Auditor traces a specific decision (optional)

    If the CTO also shared memory access, the investor can drill into any decision:

    Decision `d005: "Migrate from REST to GraphQL"` has `evidence: ["#45", "#67", "#82"]`. The investor retrieves those 3 memories:

    
      - Memory #45 — ChatGPT session discussing API performance bottlenecks

      - Memory #67 — Claude session comparing REST vs GraphQL trade-offs

      - Memory #82 — Final decision documented with rationale

    
    Each memory has its own SHA-256 hash. Content verified, provenance confirmed.

  

**What the investor can now say**
"At block 125000 on June 10, 2026, NovaTech's project had 12 active decisions backed by 82 AI conversation memories. Each decision traces to specific conversations. The state hash I verified on-chain matches exactly. Nothing was altered after anchoring."

### 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

**Important distinction**
The blockchain proves *that* a state existed at a given time. It does not reveal *what* the state contained. The owner bridges the gap by selectively sharing data with the auditor. Without the owner's cooperation, the on-chain data is opaque by design.

---

## 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.

**The fundamental guarantee**
ChainMemory ensures that AI-assisted knowledge — the decisions, discoveries, and context your team builds over weeks and months of AI-powered work — is never lost, never locked in, never falsifiable, and always portable.

---

## 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

  
    | Question | Answer | How it's enforced |

  
  
    
      | Can the operator delete an event after it's recorded? 
      | Yes, from the database 
      | But the on-chain anchor preserves the state hash. Deletion is detectable: re-computing the hash from remaining events will produce a mismatch with the anchored hash. 
    |

    
      | Can the operator modify a past state? 
      | Yes, in the database 
      | But any modification changes the state hash. Comparing the recomputed hash against the on-chain anchor reveals tampering immediately. 
    |

    
      | Can the operator forge an anchor? 
      | No 
      | Anchors are on-chain transactions. The smart contract records the state hash immutably. Forging requires controlling the blockchain — economically infeasible with PoA consensus and multiple validators. 
    |

    
      | Can a third party verify without trusting ChainMemory? 
      | Yes 
      | The verification endpoint is public and unauthenticated. Anyone can also read the smart contract directly using Web3/Ethers.js. 
    |

    
      | Can memories be read by other users? 
      | No 
      | Memory content is scoped to the API key owner. Only state hashes are public. Content never goes on-chain. 
    |

    
      | Is the memory content stored on-chain? 
      | No 
      | Only the SHA-256 hash of the consolidated state is anchored. Content stays in the API database. Privacy is preserved. 
    |

    
      | Can validators see memory content? 
      | No 
      | Validators process transactions containing only the project ID and state hash. They never see the underlying memories or content. 
    |

    
      | What happens if ChainMemory goes offline? 
      | Memories are temporarily inaccessible 
      | But all on-chain anchors remain verifiable independently. The blockchain continues operating even if the API is down. Users can export their data at any time. 
    |

  

### Trust levels

**Full trust (cryptographic)**
State integrity and timestamp. Once anchored, the hash at block N is immutable. Nobody — not even ChainMemory — can alter what was recorded.

**Operational trust (API-dependent)**
Memory storage, retrieval, injection, and consolidation. These depend on the ChainMemory API being available and honest. The anchor mechanism acts as a check: any server-side tampering is detectable.

**No trust needed**
Independent verification. Anyone with a Web3 library can read the smart contract directly and compare hashes. Zero dependency on ChainMemory infrastructure.

---

## 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

  
    | Attack | Target | Detection / Prevention | Severity |

  
  
    
      | Retroactive state modification 
      | API database 
      | ✓ Detected — recomputed hash won't match the on-chain anchor 
      | Critical 
    |

    
      | Silent event deletion 
      | API database 
      | ✓ Detected — missing events change the hash chain 
      | Critical 
    |

    
      | Fake anchor (forge tx hash) 
      | Verification layer 
      | ✓ Prevented — anchors are on-chain; forging requires blockchain control 
      | Critical 
    |

    
      | API Key theft 
      | User credentials 
      | ~ User responsibility — use env vars, rotate keys, never expose in frontend 
      | High 
    |

    
      | Man-in-the-middle on API calls 
      | Network 
      | ✓ Prevented — all API traffic uses HTTPS/TLS 
      | High 
    |

    
      | Malicious memory injection 
      | Project state 
      | ~ Mitigated — memories are scoped to API key owner; Consolidation Engine validates semantic coherence 
      | Medium 
    |

    
      | Validator collusion (>50% signers) 
      | Blockchain consensus 
      | ~ Mitigated — Clique PoA requires majority; validator set will expand to 21 seats 
      | Medium 
    |

    
      | Replay attack (resubmit old anchor) 
      | Smart contract 
      | ✓ Prevented — contract tracks version numbers; same version can't be re-anchored 
      | Medium 
    |

    
      | Content inference from hashes 
      | Privacy 
      | ✓ Prevented — SHA-256 is one-way; content can't be reversed from hash 
      | Low 
    |

    
      | DDoS on API 
      | Availability 
      | ~ Mitigated — rate limiting (30 req/min Faucet, 120 req/min Pro); blockchain unaffected 
      | Medium 
    |

  

### 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.

**Defense in depth**
ChainMemory's security model follows defense in depth: even if the centralized API is compromised, the on-chain layer provides an independent verification mechanism. No single point of failure can silently corrupt project history.

---

## 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/my-project/state/anchor

Response
{
  "project": "my-project",
  "version": 3,
  "state_hash": "a7b3c9f2e1d4...",
  "anchor": {
    "tx_hash": "0xce55a800a2a4e30b...",
    "block_number": 123539,
    "contract": "0xa7A8BA51950255b3e223a6745597C67009Fe7875"
  }
}

### 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.

  Ethers.js
  Web3.js

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 getAnchor(bytes32 projectId, uint256 version) view returns (bytes32 stateHash, uint256 blockNum, uint256 timestamp)'
];

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

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

// Read directly from the blockchain
const [stateHash, blockNum, timestamp] = await contract.getAnchor(projectId, version);

console.log('On-chain state hash:', stateHash);
console.log('Anchored at block:', blockNum.toString());
console.log('Timestamp:', new Date(Number(timestamp) * 1000).toISOString());

// Compare with the hash you received
const expectedHash = '0xa7b3c9f2e1d4...';
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: 'getAnchor',
  type: 'function',
  stateMutability: 'view',
  inputs: [
    { name: 'projectId', type: 'bytes32' },
    { name: 'version', type: 'uint256' }
  ],
  outputs: [
    { name: 'stateHash', type: 'bytes32' },
    { name: 'blockNum', type: 'uint256' },
    { name: 'timestamp', type: 'uint256' }
  ]
}];

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

const projectId = web3.utils.keccak256('my-project');

const result = await contract.methods.getAnchor(projectId, 3).call();
console.log('On-chain state hash:', result.stateHash);
console.log('Anchored at block:', result.blockNum);

### 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('0xce55a800a2a4e30b...');
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());

**Zero-trust verification**
This entire process requires zero interaction with ChainMemory's servers. You connect directly to the blockchain's RPC endpoint and read the smart contract. Even if ChainMemory's API were compromised or offline, the on-chain data remains verifiable.

**MetaMask alternative**
You can also verify visually: add the ChainMemory network to MetaMask, navigate to the contract address in the [Explorer](https://chainmemory.ai/explorer), and inspect the transaction data manually.

---

## 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 models via Ollama.

#### What is the Consolidation Engine?

It's a pipeline that analyzes your memories using a local LLM (phi3:mini) 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](#concept-conflicts) 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.

### Limits & Quotas

  | Resource | Faucet Plan | Pro Plan |

  
    | Memories per project | 500 | Unlimited |

    | Projects | 3 | Unlimited |

    | API requests/min | 30 | 120 |

    | Memory size | 10 KB | 50 KB |

    | Consolidations/day | 5 | Unlimited |

    | On-chain anchors/month | 3 | 30 |

---

### Changelog

#### 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 with phi3:mini

  - 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

---

## Public Endpoints

- Landing & Explorer: https://chainmemory.ai
- JSON-RPC: https://rpc.chainmemory.ai
- REST API: https://api.chainmemory.ai
- Faucet: https://faucet.chainmemory.ai
- Documentation: https://docs.chainmemory.ai
- Index for LLMs: https://docs.chainmemory.ai/llms.txt