supragnosis
by Ashon
README.md
# supragnosis
**Memory for AI agents that remembers who said it.**
[](https://github.com/Ashon/supragnosis/actions/workflows/rust.yml)
[](https://github.com/Ashon/supragnosis/actions/workflows/coverage.yml)
[](https://github.com/Ashon/supragnosis/actions/workflows/scenarios.yml)
[](#license)
Shared project memory for coding agents, with receipts. supragnosis is a local MCP server for
Claude Code, Codex, Cursor and other MCP clients. Your agents record what they learn as they
work, and every claim keeps who asserted it, on whose behalf, on what basis, and how far this
node trusts it. Claims that contradict each other stay side by side for you to settle, instead
of the later one overwriting the earlier.
It is built for a small team that wants one project's memory on each of its machines and
shared with teammates, without a vendor cloud: one binary, an embedded store, and no account.
A workspace leaves your machine only when you list it.
```
supragnosis = supra (above) + gnosis (knowing) - knowledge about knowledge.
```
## The problem it solves
Most agent memory answers *what was remembered*. It does not answer *who said so*.
That is fine for a single assistant remembering one user's preferences. It stops being fine
the moment two agents, two machines, or two people write into the same memory:
- Two agents assert opposite facts. Last write wins, and the disagreement is gone.
- An agent summarizes a poisoned document into memory. Nothing records where it came from,
so nothing can trace what else that summary contaminated.
- You want to share project knowledge with a teammate but not your private notes. There is
no boundary to draw, because the store has no concept of whose knowledge this is.
- A credential ends up in the log. There is no way to find it and no way to get it out.
supragnosis treats an assertion and a fact as different things. What is stored is never
"X is true" but "host H, at time T, on the basis of S, asserted X". The current belief is
computed from those assertions by a policy you can replace, so changing your mind about how
to resolve conflicts means recomputing, not rewriting.
## What that buys you
| | |
|---|---|
| **Provenance on every claim** | acting host, principal on whose behalf, workspace, source, observation time, confidence, and a trust tier the receiving node computes rather than accepts |
| **Conflicts stay visible** | contradictory assertions coexist and surface for mediation instead of one silently overwriting the other |
| **Nothing is destroyed** | the observation log is append-only and content-addressed. A correction is a new observation; a merge can be un-merged |
| **A gate before the canon** | entity merges, trust promotions, and schema changes go through a proposal with a computed diff of what the verdict would overturn |
| **Sharing is opt-in** | a workspace leaves the node only if you list it. Peers are authorized per workspace, on the sync path and the query path alike |
| **Secrets do not enter** | credential-shaped text is refused at ingest, not rewritten, because an append-only log that has replicated cannot take it back |
| **Local-first, no cloud** | one binary, an embedded pure-Rust store, no account, no network unless you configure a peer |
## Quick start
```bash
brew tap ashon/tap
brew install supragnosis-server
supragnosis service install # MCP on :7373 + local viewer, now and at every login
supragnosis connect claude-code # or claude-desktop, cursor, vscode, codex, gemini, opencode
```
`supragnosis connect` with no app lists them and says how each one is connected. It registers
`supragnosis bridge` with the app: a stdio server that relays to the daemon and reads the daemon's
bearer token from `~/.supragnosis/mcp.token` (mode 0600) itself, so no app's settings hold a copy.
That also reaches Claude Desktop, which takes local servers over stdio only. A client that wants a
URL instead can use `http://127.0.0.1:7373/mcp` with that token; `supragnosis status` prints the
command, reading the token from its file rather than printing it.
With Claude Code, `connect` also registers a hook, so the memory fills without being asked: after a
commit the agent made, it is asked for the decision behind the change that the diff does not show,
and a session starts knowing what the project's workspace holds here. `--no-capture` leaves the
hook out; the hook never writes anything itself ([docs/client-connect.md](docs/client-connect.md)
Section 12).
With the desktop app (`brew install --cask supragnosis`), its Settings page (Settings... in the tray,
or Cmd+,) does both without a terminal: Start at Login keeps the daemon running, and AI apps connects
Claude Desktop, Claude Code and the others with a click. After `brew upgrade`, `supragnosis restart` loads the new binary -
until then `supragnosis status` and the tray say the daemon is running the old one.
Not on Homebrew:
```bash
curl -fsSL https://supragnosis.dev/install.sh | sh # ~/.local/bin, checksum-verified
supragnosis service install # macOS; Linux: deploy/systemd
supragnosis connect claude-code
```
Retrieval is semantic as well as keyword: a local embedding model (multilingual, 224 MB, no API
calls) that `service install` fetches once into `~/.supragnosis/models`, or `supragnosis embed
fetch` does by hand. Until it is there, retrieval is keyword only and `supragnosis status` says
so. The daemon holds about 1 GB once a tool call has loaded the model; `SUPRAGNOSIS_EMBED=none`
keeps it keyword only and small ([docs/semantic-retrieval.md](docs/semantic-retrieval.md)).
Removing it takes the daemon off login, disconnects each AI app and deletes the binary, and leaves
the knowledge in `~/.supragnosis` unless you remove that too
([deploy/README.md, Operations](deploy/README.md#operations)).
### Your first minute
Ask the agent to remember something, in whatever words you would use:
> **you:** remember that auth in this repo is JWT with a 15-minute expiry, decided because the
> mobile client cannot hold a session cookie
The agent calls `observe`. What lands is not the sentence - it is an observation carrying the
entities it names, the relations between them, and who said it:
```
observed "auth in this repo is JWT with a 15-minute expiry..."
entities JWT [AuthMechanism], mobile client [Component]
relations repo --uses--> JWT, JWT --constrained_by--> mobile client
provenance host=your-laptop on_behalf_of=you tier=agent_extracted
```
Later, in a different session, with none of that in the context window:
> **you:** how does auth work here?
>
> **agent:** JWT with a 15-minute expiry. That came from you directly rather than from reading the
> code, and the stated reason was that the mobile client cannot hold a session cookie.
The second half of that answer is the point. A search hit is the id of what matched, and that id
leads to the provenance: `get_entity` lists every attestation behind an entity, and the observation
it came from (`supragnosis://observation/{id}`) has the original text and who said it, for whom and
when. So the agent can tell you *who said it and how sure to be*, and you can read it yourself.
The viewer runs alongside the daemon on a unix socket - the desktop app opens it, or read it
directly:
```bash
curl -s --unix-socket ~/.supragnosis/viz.sock http://localhost/api/graph
```
Watching it while an agent works is the part that is hard to convey in text:
<p align="center">
<img src="site/assets/viewer.webp" alt="The supragnosis viewer: an entity/relation graph with a curation panel beside it" width="820">
</p>
## What the agent gets
13 MCP tools, each one recurring intent:
- `observe` - free text plus optional structured assertions. No schema required up front.
- `search_knowledge` - keyword retrieval (every term, any order) plus semantic, labelled with the
mode it used.
- `get_entity`, `traverse` - exact lookup and bounded graph walks.
- `workspace_map` - co-occurrence hyperedges: what tends to get said together.
- `define_type` - promote a pattern into the workspace glossary.
- `propose`, `review`, `list_proposals`, `get_proposal` - the gate to the canon.
- `sync_status`, `sync_pull`, `sync_push` - federation.
Plus dereferenceable resources: `supragnosis://workspaces`,
`supragnosis://workspace/{ws}/graph`, `supragnosis://workspace/{ws}/hypergraph`,
`supragnosis://workspace/{ws}/types`, `supragnosis://observation/{id}`.
## What you get
Four MCP prompts, which a client offers as commands (in Claude Code, `/mcp__supragnosis__brief`):
- `brief` - what a workspace's knowledge says now: its themes, what is contested, what rests on a
single agent claim, and what is waiting on your decision.
- `what-do-we-know-about` - what the store holds on one topic, with sources, and what it does not.
- `curate` - the model drafts proposals for the tidy-ups the curation signals point at.
- `review-proposal` - a first-pass review of one proposal: what merging it would change, and a
recommendation.
Your model writes the brief from current state and nothing is stored. A judgment worth keeping
becomes a proposal, and you cast the verdict in the app's Review panel. The canon is what remains,
and the next brief reads it. See [docs/prompts.md](docs/prompts.md).
## How it works
Three ideas, and everything else follows from them.
**Event sourcing.** Immutable, content-addressed observations are the source of truth. The
entity and relation graph is a projection you can throw away and rebuild by replaying the
log. Changing the resolution policy is a re-projection, not a migration.
**Topology-independent convergence.** Nodes holding the same set of observations materialize
the same graph, no matter which path events took or in what order they arrived. Content
addressing dedups, hybrid logical clocks order, and the projection is a deterministic fold.
Local-only, hub-and-spoke, direct peer, or a mix: the topology is an operational choice, not
a semantic one.
**Hexagonal ports.** The domain crate has zero IO dependencies. Store, embedder, and
transport sit behind ports held to one conformance suite. This is not an aspiration: a third
store adapter was added and the original backend deleted, a different query paradigm and a
different storage engine, without changing a line of `core` or `engine`.
## Documentation
| | |
|---|---|
| [architecture.md](docs/architecture.md) | what is built, how, and Section 14: the honest record of what is not |
| [principles.md](docs/principles.md) | the normative document. Every design decision is justified against it |
| [federation.md](docs/federation.md) | node identity, the sync protocol, trust evaluation |
| [proposal-workflow.md](docs/proposal-workflow.md) | the gate to the canon |
| [resolution.md](docs/resolution.md) | how assertions become a current belief |
| [excision.md](docs/excision.md) | the one act that removes knowledge, and why it is last |
| [consolidation.md](docs/consolidation.md) | how a workspace stays tidy without anything being deleted |
| [CONTRIBUTING.md](CONTRIBUTING.md) | how to build, test, and send a change |
## Status
Working today: hybrid retrieval, belief resolution with contested claims surfaced, identity
resolution with an entity merge gate that can be reversed, hub-and-spoke log replication with
ed25519-signed events over TLS, and a live viewer.
Not yet: bitemporal time-travel queries, multi-principal governance, retrieval demotion and idle
consolidation, and automatic type induction.
That second list is not a roadmap gesture. Every unmet demand is a named clause with a
declared evidence state, tested by
[`principle_coverage.rs`](crates/supragnosis-engine/tests/principle_coverage.rs), and every
deferral names the milestone that repays it. If a guard is deleted or renamed, the clause
reports itself as unguarded. See [architecture.md](docs/architecture.md) Section 14.
**Compatibility.** A store is never misread. A release upgrades a store an earlier one wrote, in
place. It refuses a store a later release changed past it, and changes nothing in it: the message
names the release to install. An id or a signature, once made, verifies under every later build.
Before 1.0 a minor release may raise what a store requires, and its release note says so first.
The CLI's `--json` answers carry a schema number. A breaking change to the MCP tools is listed
under [Breaking changes](CHANGELOG.md#breaking-changes). The whole promise, and what it leaves to
federation's design (the sync wire), is [docs/compatibility.md](docs/compatibility.md).
## Configuration
Everything has a default that works. `supragnosis --help` for the full surface;
[docs/architecture.md](docs/architecture.md) for the reasoning behind the defaults.
Most used:
- `SUPRAGNOSIS_WORKSPACE` - default workspace (default `default`)
- `SUPRAGNOSIS_DATA_DIR` - store directory (default `~/.supragnosis/redb`)
- `SUPRAGNOSIS_EMBED` - `fastembed` (default) | `hashing` | `none`. `none` is keyword only
- `SUPRAGNOSIS_EMBED_MODEL` - `multilingual` (default) | `bge-small-en` (English only, half the size)
- `SUPRAGNOSIS_CONFIG` - path to `supragnosis.toml`. No file means a standalone node
- `SUPRAGNOSIS_MCP_AUTH` - `on` (default) | `off`. `off` drops the daemon's bearer check
The MCP HTTP daemon is loopback-only **and requires a bearer token**. Those are two different
guards because loopback answers a different question than people assume: it confines the surface
to this *host*, not to one *user*, so on a shared machine any local account could otherwise
`observe`, `review` and `sync_push` through it. The token (`~/.supragnosis/mcp.token`, mode 0600)
is what makes the surface yours, and it is the same access control the viewer gets from its socket
file - the viewer could move to a unix socket, and the daemon cannot, because MCP clients speak
HTTP.
The viewer has no TCP port at all: it serves over a unix socket whose 0600 mode is the access
control, and every response carries a Content-Security-Policy. A non-loopback federation bind
requires TLS and someone admitted (a node or an open invitation), and refuses to start otherwise.
A second machine joins with a code: `supragnosis invite` on the machine that will be the hub,
`supragnosis join` on the other ([docs/pairing.md](docs/pairing.md)). Each keeps its own daemon,
and the two sync.
## Upgrading from a pre-0.2 store
Through v0.1.21 the store was Cozo. This build reads only redb and refuses to start beside an
un-migrated Cozo store rather than coming up empty next to one. Read
[docs/store-migration.md](docs/store-migration.md) Section 5 first, then:
```bash
supragnosis stop
curl -fsSL https://supragnosis.dev/install.sh | sh -s -- --version v0.1.21
supragnosis migrate-store
curl -fsSL https://supragnosis.dev/install.sh | sh
supragnosis start
```
## License
MIT OR Apache-2.0, at your option. See [LICENSE-MIT](LICENSE-MIT) and
[LICENSE-APACHE](LICENSE-APACHE).
Unless you state otherwise, any contribution you intentionally submit for inclusion is dual
licensed as above, with no additional terms.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo issues