One brain for every AI you use — private, portable, and yours.
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
- Shape it. Run
/context-initand answer a few questions about what's worth remembering here — subsystems? decisions? features? It drafts and installs the topology. - Work normally. As you make decisions,
capturerecords them with provenance — what was decided, why, and which code it touches. You never stop to write anything down. - Recall in a new session. "How does the projector work, and what did we decide about
locking?" →
/recallanswers from the graph and cites the source of every claim. - Extract what's reusable.
/componentizeturns the repo into capability components — feature-level capabilities, not app glue. - Reuse it elsewhere. From a different project: "pull in the search feature I built on
myrepo" →
/reusefetches 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
- Create and switch from chat.
/manage-memorylists what you have, makes new ones, and switches the active memory — no terminal, no restart. - File facts in the right place. Every write tool takes
profile=, so an agent can route a fact toresearchwhile working inwork, in one call, without switching. Cross-memory targeting is always explicit; isolation is what you get by default. - 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.
- Facts merge instead of colliding. When two agents both write about "Acme", resolution folds them into one entity rather than piling up duplicates.
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.