supragnosis

supragnosis

Memory for AI agents that remembers who said it.

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. A server on another machine is added there too. 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 list is not a roadmap gesture. Every unmet demand is a named clause with a declared evidence state, tested by 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 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. The whole promise, and what it leaves to federation's design (the sync wire), is docs/compatibility.md.

Configuration

Everything has a default that works. supragnosis --help for the full surface; 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 a principal), and refuses to start otherwise.

Using a server from another machine

A node with a [server] listener - usually the hub - can serve MCP to people and agents on other machines (docs/remote-server.md). On the server, the operator admits each one with the workspaces it may read and write. Its credential is shown once and stored only as a hash:

supragnosis principal add alice --read docs --write team

On the other machine, a server profile points every AI app at it. The apps stay configured with supragnosis bridge and never see the credential:

supragnosis server add home https://hub.example:7420/mcp   # paste the credential when asked
supragnosis server use home                                # `server use local` to go back

An agent with its own HTTP MCP client sends the credential as Authorization: Bearer ... to https://<hub>/mcp.

The remote surface reads and ingests within the grants. Verdicts, type definitions and sync are refused there until principals can sign their own acts. Knowledge another node shared with the hub is served only if that node lists the workspace in [sync] serve_workspaces.

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 Section 5 first, then:

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 and LICENSE-APACHE.

Unless you state otherwise, any contribution you intentionally submit for inclusion is dual licensed as above, with no additional terms.