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 anchor is the proof of existence — 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 — SHA3-256 of the canonical state, domain-separated with CM_PROJECT_STATE_V<schema_version>, 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
• Consolidate regularly — each consolidation creates a new state version, which is then anchored on-chain. seal is a different operation: it makes a single memory permanently immutable
• 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:

• Client-driven — an AI model proposes operations through update_project_state (MCP) or POST /v1/project/:name/state/ops (API). The server validates them and only then do they become state
• No automatic trigger — consolidation never happens on its own. Nothing is ever written to your state unless a client proposes it

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

A state anchor contains only the hashed project identifier, the version number, the state hash and a timestamp. A memory transaction additionally carries the encrypted content plus its category, importance and plaintext length. From either one it is impossible to reconstruct the content without the owner key.

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