Skip to main content

CanonGraph

One brain for every AI you use — private, portable, and yours.

Apache 2.0 CI Python 3.10-3.13 Runs locally


Memory for your AI, that you own

Every time you close a chat, your AI forgets. You re-explain your projects, your team, your decisions — and your knowledge ends up trapped inside whichever model you happened to use.

CanonGraph gives your AI a persistent memory it builds as you work — a private knowledge graph of your projects, people, decisions and documents, stored on your machine in your own files.

The memory belongs to you, not to any one AI. Any assistant can plug into it over MCP or plain HTTP — Claude today, something else tomorrow — and you keep everything. No account, no cloud, Apache-2.0.


Install & set up

1. Install the binary.

uv tool install canongraph        # recommended
pipx install canongraph           # or pipx
pip install canongraph            # or plain pip

CanonGraph supports Python >=3.10,<3.14, and the package metadata declares that range, so uv picks a compatible interpreter itself. If an installer ignores that metadata and reaches for Python 3.14, point it at any installed 3.10–3.13 interpreter and retry.

2. Create a memory.

canongraph init --name work                          # a ready-to-use starter you can edit
canongraph init --name deals --template buyout-pe    # or start from a bundled template

A topology — the shape of what you remember — is not required to start. Every memory ships with a generic starter shape, so you can capture from minute one and add structure later.

3. Connect your agent.

The smoothest path is the Claude Code plugin, which registers the MCP server for you:

/plugin marketplace add jvattimo1/canongraph
/plugin install canongraph@canongraph
/context-init

The plugin registers the server config, but it still needs the canongraph binary on your PATH (uv tool install canongraph) for that server to actually run — /context-init checks first and tells you if it's missing.

For any other MCP client, print or write the config directly:

canongraph config --client claude-desktop      # prints the snippet to paste
canongraph config --client cursor --write      # or merge it in for you

4. Check it's healthy.

canongraph doctor      # → status: OK

Skills & MCP tools

The seven skills

Installed with the Claude Code plugin. This is where the judgment lives — the engine itself stays deterministic and headless.

Skill What it does
/context-init Interviews you about your world, drafts a topology, installs it.
capture Runs in the background — records salient facts with provenance as you work.
/recall Answers a question from your memory, resolving entities and citing sources.
/manage-memory List, create, switch, extend and delete memories from chat.
/componentize Breaks a codebase into reusable capability components.
/reuse Pulls a captured capability's card + code snapshots into your current project.
/component-audit Reviews and trims the component library.

It keeps itself up to date

You don't hand-feed CanonGraph. Your assistant captures durable facts as you work using your own model — the engine never calls an LLM. When it's unsure it records the fact at low confidence and the pruning policy quietly demotes it out of trusted recall, so guesses never pollute what you get back. You keep the final say: canongraph shaky lists what it's least sure of, and canongraph confirm <target> vouches for a fact so automated pruning can never touch it.

Env var Effect
CANONGRAPH_NO_AUTOCAPTURE=1 Turn off all automatic capture at session end.
CANONGRAPH_NO_AUTODEMOTE=1 Keep capture, skip the unsure-fact demote.
CANONGRAPH_DEMOTE_FLOOR=0.35 The confidence below which a fact is treated as unsure.

The tools your agent calls

40 MCP tools, grouped by job. Every tool takes an optional profile= to target another memory; omit it and you get the active one. Isolation is the default.

Job Tools
Remember ingest · ingest_document · ingest_transcript · drain_inbox
Recall search (hybrid vector + keyword) · query · describe_entity · get_document · get_topology · resolve · benchmark · list_profiles · view
Trust & verify shaky_facts · contradictions · gaps · merge_candidates · provenance_query · capture_status · memory_status · prune_preview · prune_status
Curate & fix confirm · merge · alias · promote_property · unify_property · extend
Forget retract · redact · distrust · purge · prune · prune_commit · prune_undo
Manage memories use_profile · create_profile · rename_profile · delete_profile · configure_capture

Run canongraph -h for the CLI equivalent — 30 subcommands, each taking --profile NAME.

Any model — MCP or REST

CanonGraph isn't locked to one assistant. It works out of the box with any MCP-capable client (Claude Code, Claude Desktop, Cursor, Cline), and a thin JSON/HTTP API over the same memory lets any app or model read and write it without MCP. Run CG_TRANSPORT=http canongraph serve and both surfaces are served on one port behind one bearer token.


Workflow

Example A — a memory for one codebase

Give an agent lasting context on a repo: its architecture, its decisions, and why things are the way they are.

canongraph init --name myrepo
  1. Shape it. Run /context-init and answer a few questions about what's worth remembering here — subsystems? decisions? features? It drafts and installs the topology.
  2. Work normally. As you make decisions, capture records them with provenance — what was decided, why, and which code it touches. You never stop to write anything down.
  3. Recall in a new session. "How does the projector work, and what did we decide about locking?" → /recall answers from the graph and cites the source of every claim.
  4. Extract what's reusable. /componentize turns the repo into capability components — feature-level capabilities, not app glue.
  5. Reuse it elsewhere. From a different project: "pull in the search feature I built on myrepo" → /reuse fetches the capability card plus code snapshots and adapts them to the current stack.

Inspect what it knows any time with canongraph view — a private local page showing the live graph and every node's sources. canongraph digest prints what changed since you last looked.

Example B — several memories, several agents

Keep separate memories per project or domain, and let more than one agent work against them.

canongraph init --name work
canongraph init --name research
  1. Create and switch from chat. /manage-memory lists what you have, makes new ones, and switches the active memory — no terminal, no restart.
  2. File facts in the right place. Every write tool takes profile=, so an agent can route a fact to research while working in work, in one call, without switching. Cross-memory targeting is always explicit; isolation is what you get by default.
  3. Point several agents at one memory. Reads run concurrently. Writes are taken one at a time by a single-writer lock, so two agents writing at the same instant can't corrupt anything or overwrite each other — a write just waits its (millisecond) turn.
  4. Facts merge instead of colliding. When two agents both write about "Acme", resolution folds them into one entity rather than piling up duplicates.
  5. Produce something. Recall feeds the deliverable — ask an agent to draft the summary, report or migration plan from the memory, and every claim traces back to a source you can check.

For one person on one machine the default embedded mode is all you need. For a team sharing one memory, run CG_TRANSPORT=http canongraph serve backed by Postgres + Neo4j (pip install "canongraph[server]").

Honest trade-off: writes are serialized rather than truly parallel. For a memory layer that's the right call — correctness first — and reads, the common case, are fully concurrent.


Architecture

CanonGraph is event-sourced. Everything you tell it is appended to an immutable log — the single source of truth. The queryable graph and the search index are projections rebuilt from that log, so your memory is always reconstructable and never silently corrupted.

  your topology (what to remember)
            │
            ▼
    ┌───────────────┐     ┌──────────────┐     ┌───────────────────┐
    │  event log    │ ──► │  projector   │ ──► │  knowledge graph  │ ──► MCP / REST
    │ (source of    │     │ (rebuildable │     │  + hybrid search  │     (your agents
    │   truth)      │     │  projections)│     │                   │      work here)
    └───────────────┘     └──────────────┘     └───────────────────┘

Two layers, one memory. A structured layer — the tidy graph of things and relationships you query precisely — and a document layer for everything else (notes, files, transcripts) kept whole and searchable by meaning. Nothing is lost because it didn't fit a category, and the things you care about stay clean and queryable.

Storage. Embedded by default: SQLite for the log, Kùzu for the graph, and a small local embedding model — no Docker, no external services, no API key. Flip to Postgres + Neo4j for a shared server. canongraph rebuild replays the log and reconstructs every projection from scratch.

Your data. Everything lives in plain files under ~/.canongraph/, created private (0700/0600). Nothing is sent anywhere; the one network call is a one-time download of the local embedding model, pinned to an exact commit and then cached. canongraph redact physically removes a document — text, chunks and embeddings — so "forget" means forget.

Where the limits are. Current boundaries are documented plainly in LIMITATIONS.md, the security model in SECURITY.md, and what's next on the roadmap.

From source:

git clone https://github.com/jvattimo1/canongraph.git
cd canongraph
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Contributions welcome — see CONTRIBUTING.md.

License

Apache License 2.0. All demo data is synthetic.

Metadata

Release files for canongraph 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for canongraph 0.3.0
File Size Uploaded Provenance Actions
canongraph-0.3.0.tar.gz 751.9 kB Without provenance Details for canongraph-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for canongraph 0.3.0
File Interpreter ABI Platform Actions
canongraph-0.3.0-py3-none-any.whl Python 3 none any Details for canongraph-0.3.0-py3-none-any.whl

Total release size: 1.2 MB

Release files / canongraph-0.3.0.tar.gz

Download URL canongraph-0.3.0.tar.gz
Size 751.9 kB
Tags Source
SHA-256 checksum
How to use checksums
ed3904cbda8b14c926f074489da6a906a63db75a89ca51164402ae4e62116ce5
BLAKE2b-256 checksum
How to use checksums
1df01cf43dec956761fd1f17a8ba8f6465dcd1f20614f29007578f0ae1fb265a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.13

Release files / canongraph-0.3.0-py3-none-any.whl

Download URL canongraph-0.3.0-py3-none-any.whl
Size 430.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
721a5ab4cdf2fae35aac9adfa2007a2231790a8c2d48f3edb592c49aa913393d
BLAKE2b-256 checksum
How to use checksums
8dc3bec8a7fc130f928c8ce890a95a51561b6a16fdf12441d3c31153eecea0a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.13

Security for canongraph 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page