How it works

Drop-in compatible. Radically simpler.

A Neo4j driver, talking to CognoDB. No changes. The same code you'd write against a Neo4j cluster works against a CognoDB binary running on your laptop, your CI box, or thousands of edge devices.

1. Write & recall memory

Two MERGE statements create a user and a fact, then link them with a typed edge that carries a timestamp. One MATCH reads it back. This is the entire shape of agent memory.

python

from neo4j import GraphDatabase

driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("neo4j", "password"),
)

with driver.session() as session:
    session.run("""
        MERGE (u:User {id: $uid})
        MERGE (f:Fact {text: $fact})
        MERGE (u)-[:REMEMBERS {at: datetime()}]->(f)
    """, uid="maya", fact="Prefers concise answers")

    result = session.run("""
        MATCH (u:User {id: $uid})-[:REMEMBERS]->(f:Fact)
        RETURN f.text AS memory
    """, uid="maya")
    for r in result:
        print(r["memory"])

2. Pick the deployment shape

Same binary, same Bolt port, same Cypher. The flag decides the lifecycle and the persistence story.

bash · lifecycle

# ephemeral session memory
./cognodb

# durable per-agent memory
./cognodb --storage local --data-dir ./mem

# shared knowledge base
./cognodb --sharded --num-shards 3

bash · storage backend

# managed Mongo cluster
./cognodb --storage mongo \
  --mongo-uri "mongodb+srv://..." \
  --mongo-db cognodb

# durable, embedded, single file
./cognodb --storage local --data-dir /var/lib/cognodb

3. Deploy anywhere

One static binary, one container, or one scp command. No JVM, no daemon to install, no operator to maintain.

bash · container

# Docker (FROM scratch, tiny image)
docker run -p 7687:7687 \
  ghcr.io/cognodb/cognodb:latest

# Kubernetes — one pod per tenant
kubectl apply -f cognodb-per-tenant.yaml

bash · edge

# Edge device: just copy the binary
scp cognodb pi@edge-node:/usr/local/bin/

# Or run inside the agent process itself
./agent --embed-cognodb

4. Snapshot, replay, branch

The graph is yours. Dump it to JSONL, version it, ship it. Replay an entire reasoning session deterministically; fork a snapshot to explore a what-if without touching the original.

bash

# dump current graph
cognodb-dump --out ./snapshots/2026-06-01.jsonl

# restore into a fresh process
./cognodb --restore-from ./snapshots/2026-06-01.jsonl

# fork: same snapshot, two processes, different futures
./cognodb --restore-from snap.jsonl --port 7687 &
./cognodb --restore-from snap.jsonl --port 7688 &

Migrate

About