supragnosis

supragnosis

Agent memory you can cross-examine.

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

Quick start

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

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).

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).

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:

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:

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.

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

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 l