open-cognition

Open-Cognition Logo

Open-Cognition

Open-Cognition is a reference substrate for governed shared memory between autonomous and human-directed agents.

It separates immutable canonical objects (facts) from agent-scoped references (meaning), and provides a minimal control layer for attribution, auditability, and a safe system halt.

This repository defines a reference architecture, not a product.

📋 Contents

🧭 Purpose

Most shared AI systems, like agent networks and systems of agents, lose attribution and history as they evolve.

Open-Cognition ensures that:

The Problem

Modern AI systems can write to shared state without leaving a reliable trail of:

The Solution

Open-Cognition addresses this by defining a minimal, reproducible substrate with:

The goal is not to constrain agent behavior, but to make the shared system state inspectable, attributable, and reversible at the level of human control.

What this is not

Open-Cognition is not:

It is a base layer substrate for recording and attributing changes to a system, not a system that decides what is true.

[!IMPORTANT] Open-Cognition records system state; it does not determine what is true or resolve conflicts.

🚀 Quick Start

Prerequisites

Run

git clone https://github.com/bjl13/open-cognition
cd open-cognition
make up       # starts Postgres, MinIO, and the control plane
make migrate  # applies the database schema

After startup:

Service Address
Control Plane + Dashboard http://localhost:8080
MinIO Console http://localhost:9001 (minioadmin / minioadmin)
MinIO API http://localhost:9000
Postgres localhost:5432

Verify

make smoke    # full round-trip: create object → verify storage → test immutability

make smoke creates a canonical object, verifies the returned ID matches the SHA-256 of the submitted payload, and confirms duplicate rejection (409). Exit 0 means the substrate is working.

From the dashboard at http://localhost:8080 you can inspect system mode, canonical objects, agent references, and the audit log in real time.

Local Development

To build and run the control plane outside Docker:

cp .env.example .env   # set CONTROL_API_KEY and storage credentials
make build             # compiles ./control-plane
./control-plane

Other useful targets:

make logs       # tail all service logs
make down       # stop all services
make validate   # validate schemas against example files
make export     # export canonical objects to backups/ (NDJSON)
make backup     # dump Postgres to backups/ (gzip SQL)
make reconcile  # verify every ledger object exists in storage

📦 Repository Structure

open-cognition/
│
├── schemas/        # Canonical object, reference, and policy schemas
├── examples/       # Minimal example records
├── cmd/            # Control plane entrypoint (Go)
├── internal/       # API, DB, models, lifecycle
├── agents/         # Sample agent implementations
├── dashboard/      # Compiled static UI
├── migrations/     # Database schema
├── scripts/        # Operational scripts (smoke test, backup, export, reconcile)
├── docs/           # Architecture and governance notes
└── roadmap.md      # Live development intent document (see Roadmap)

🧱 Core Concepts

Canonical Objects (Fact Layer)

Unchanging, content-addressed records.

Properties:

Canonical objects form the system’s shared source of truth.

Agent References (Meaning Layer)

Agent-scoped pointers to canonical objects.

They express:

Agents cannot own objects.
They own their interpretation of them.

Event Ledger

All state changes are recorded as append-only events:

History is never rewritten.
Attribution is always preserved.

System Lifecycle

A global control mode governs whether the system can mutate state:

When stopped:

This provides a universal, independently-invocable halt mechanism.

🧠 Mental Model

Open-Cognition separates system memory into two layers:

Agents do not modify shared truth.
They interpret it.


---
config:
  elk:
    mergeEdges: true

  look: neo
  theme: neo
  layout: dagre
---

flowchart TB
 subgraph AP["Agentic Plane"]
    direction LR
        A["Agent"]
  end
 subgraph DL["Data Layer"]
    direction LR
        REF["Reference"]
        J[" "]
        O["Canonical Object Store"]
        E["Event Ledger"]
  end
 subgraph CP["Control Plane"]
    direction LR
        C["Control Plane"]
  end
    A ~~~ REF
    REF ~~~ C
    REF --> J
    J -- *records in* ------> E
    A -- *creates* --> REF
    J -- *points to* --> O
    C -. *governs* .-> REF
    C -. *enforces* .-> E
    E -- *describes* ---> O

    A@{ shape: rounded}
    REF@{ shape: notch-rect}
    J@{ shape: f-circ}
    O@{ shape: cyl}
    E@{ shape: bow-rect}
    C@{ shape: hex}
     A:::core
     REF:::core
     O:::core
     E:::core
     C:::control
    classDef core fill:#BDAECD,stroke:#CDA433,stroke-width:2px
    classDef control stroke:#6EC8C2,fill:#EA8A7C,stroke-width:2px
    style A fill:#6EC8C2,stroke:#BDAECD

Open-Cognition separates system memory into two layers:

🏗️ Architecture Overview

Open-Cognition consists of four minimal components:

An optional static dashboard provides read-only visibility into system state.

→ See docs/architecture.md for full component detail and local development notes, docs/architecture-diagram.md for the component diagram, and docs/data-flow-diagram.md for the write-path sequences.

⚙️ Example Use Case

An agent analyzes a document:

  1. A report is stored as a canonical object
    → obj:sha256:9f3c…

  2. The agent emits a reference
    → ref:agent-A:001 → obj:9f3c…

  3. The reference encodes interpretation
    → { tag: "financial", relevance: 0.8, horizon: "short-term" }

  4. An event is appended to the ledger
    → { actor: "agent-A", action: "reference.create", object: "obj:9f3c…" }

  5. A second agent emits a conflicting reference
    → { tag: "incomplete", relevance: 0.3 }

The object is immutable; disagreement is expressed through references, not mutation.

No interpretation overwrites another and all perspectives remain attributable.

Because objects are immutable and references are isolated, interacting agents cannot overwrite or compound each other’s errors.

[!TIP] When agents can observe each other’s references, disagreement becomes visible—enabling comparison, correction, and potential convergence over time.

🛡️ Governance Model

Open-Cognition enforces three key separations:

  1. Fact vs Interpretation
    Canonical objects are immutable. References carry meaning.

  2. Actor vs System
    All mutations are attributable to specific agents or humans.

  3. Execution vs Memory
    Agents compute locally but cannot directly mutate shared truth.

→ See docs/governance-model.md for canonical object rules, reference requirements, policy objects, system halt behaviour, and audit log semantics. See docs/trust-model.md for the identity, signing, and TOFU-key details, docs/lifecycle.md for system / object / reference lifecycles, and docs/threat-model.md for adversary assumptions and residual risks.

⚜️ Design Principles

🗺️ Roadmap

roadmap.md is a live working document tracking development phases, current status, known technical debt, and design rationale. It is not a governance document — it reflects development intent and internal reasoning, not system contracts.

It is intentionally surfaced here as a reference point for contributors and agentic coding tools. Reading it before working on the codebase will give you accurate context on what is complete, what is deferred, and why specific tradeoffs were made. It is the right place to look before proposing changes or extensions.

Current state: Phases 0–8 complete. Phase 9 (v1.0 freeze readiness) is next — see docs/v1-readiness.md.

📜 License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

The core substrate remains open while allowing independent extensions and commercial implementations.

This site is open source. Improve this page.