Metadata-Version: 2.4
Name: canongraph
Version: 0.3.0
Summary: An embeddable, event-sourced context graph with an MCP interface. Zero external dependencies by default (SQLite + Kùzu); scales to Postgres + Neo4j. Define your domain in one topology YAML.
Author: jvattimo1
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/jvattimo1/canongraph
Project-URL: Repository, https://github.com/jvattimo1/canongraph
Project-URL: Issues, https://github.com/jvattimo1/canongraph/issues
Keywords: context-graph,knowledge-graph,mcp,model-context-protocol,event-sourcing,graph-database,embeddings,rag,llm,kuzu,neo4j
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: mcp<2,>=1.2
Requires-Dist: uvicorn>=0.30
Requires-Dist: model2vec>=0.3
Requires-Dist: kuzu>=0.11
Provides-Extra: server
Requires-Dist: psycopg[binary]>=3.1; extra == "server"
Requires-Dist: psycopg-pool>=3.2; extra == "server"
Requires-Dist: neo4j>=5.20; extra == "server"
Provides-Extra: st
Requires-Dist: sentence-transformers>=2.2; extra == "st"
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0; extra == "pdf"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: canongraph[server,st]; extra == "dev"
Dynamic: license-file

<!-- LAUNCH STEP: these logo paths are RELATIVE so they render on GitHub while the repo is private.
     At go-public, switch both to absolute (https://raw.githubusercontent.com/jvattimo1/canongraph/main/assets/…)
     so the logo also renders on the PyPI page. Absolute raw URLs only resolve once the repo is public. -->
<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/canongraph-logo-dark.svg">
    <img src="assets/canongraph-logo.svg" alt="CanonGraph" width="420">
  </picture>
</p>

<p align="center"><b>One brain for every AI you use — private, portable, and yours.</b></p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache 2.0"></a>
  <a href="https://github.com/jvattimo1/canongraph/actions/workflows/ci.yml"><img src="https://github.com/jvattimo1/canongraph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/python-3.10--3.13-blue.svg" alt="Python 3.10-3.13">
  <img src="https://img.shields.io/badge/runs-100%25_local-14b8a6.svg" alt="Runs locally">
</p>

---

## 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](https://modelcontextprotocol.io) 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.**

```bash
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.**

```bash
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:

```bash
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.**

```bash
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.

```bash
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.

```bash
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](https://sqlite.org) for the log,
[Kùzu](https://kuzudb.com) 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](LIMITATIONS.md)**, the security model in **[SECURITY.md](SECURITY.md)**, and
what's next on the **[roadmap](ROADMAP.md)**.

**From source:**

```bash
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](CONTRIBUTING.md).

## License

[Apache License 2.0](LICENSE). All demo data is synthetic.
