supra (above) + gnosis (knowing)
Your agents' memory is trapped: one vendor, one machine, no record of where any of it came from. supragnosis hands it back - an embedded, file-based knowledge server in Rust where agents shed observations as a by-product of work, the knowledge travels between your machines, tools and team, and every claim arrives carrying who said it, on what basis, and how far to trust it. Humans govern what becomes canon. Any MCP client, any host, any workspace.
curl -fsSL https://supragnosis.dev/install.sh | sh
01 / agent-first
agents
Knowledge management dies the moment it becomes separate labor - so here it is a by-product of work. While your agents code, debug, and decide, they shed observations through one low-friction tool: free text plus whatever structure they can already offer. No forms, no curation shift.
agents
No ontologist draws the taxonomy up front. Unknown knowledge lands as
loose concepts, patterns harden with use, and agents promote them
through define_type - every type with a mandatory
plain-language definition. The workspace map keeps score of what is
said together, so the next type worth naming surfaces on its own.
humans
Ingest is free; canon is governed. Entity merges, trust promotions, and vocabulary changes travel through PR-like proposals that a human reviews in the curation console - and the tier a verdict may grant depends on the surface it arrives on, so an agent-cast verdict cannot reach human-confirmed.
02 / guarantees
Every answer can say where it came from. The log never stores "X is true" - it stores who observed X, acting for whom, when, with what confidence. Belief is computed on top by a replaceable policy, so changing whom you trust recomputes the belief from the same log.
Nothing your agents learn is ever lost. Corrections supersede rather than erase, contradictions surface as signals instead of being silently resolved away, and forgetting only demotes recall - the log is eternal; only attention is finite.
No model ever judges your knowledge. LLMs and embeddings extract and widen recall - they draft, they never decide. Everything that commits is deterministic, so the graph is correct with no model attached at all, and every node holding the same log holds the same graph.
The name is the design: observations that mention the same things leave a second-order structure behind - knowledge about the knowledge. That meta layer (supra + gnosis) is what the workspace map shows, and what curation reads when it proposes the next merge or type.
03 / how it works
The log is the source of truth. Delete the graph, replay the log, and you get the same graph back - on any node, in any topology.
# one observe call, free text plus whatever
# structure the agent already has
observe {
"content": "Replaced Cozo with redb: of nineteen
query shapes exactly one was recursive
and none used time travel.",
"source_ref": "docs/architecture.md",
"on_behalf_of": "ashon",
"confidence": 0.9,
"entities": [
{ "name": "redb", "type": "Tool" }
],
"relations": [
{ "from": "supragnosis-store",
"type": "depends_on",
"to": "redb" }
]
}search_knowledge {
"query": "why redb and not a datalog store?"
}
# the hit comes back with its receipts:
# the original text, plus who observed it,
# acting for whom, from which source, when,
# at what trust tier - and the mode label
# (hybrid vs keyword) that says which recall
# surface answered.
# hits carry stable entity ids - pull the thread:
get_entity { "id": "9f41..." } # id from the hit
traverse { "id": "9f41...", "max_depth": 2 }04 / the viewer
05 / capabilities
Ask in your own words - "why redb and not a datalog store?" - and the fragment comes back. Vector search over local ONNX embeddings (fastembed) fuses with keyword search, deterministically ranked and mode-labeled so you know which surface answered. Without an embedder it degrades to keyword. No cloud calls either way.
Every fact carries its delegation chain (who, acting for whom), workspace, and trust tier - and trust is the receiver's evaluation, never self-declared. Every derivation records the observations it came from, so a contaminated source's tree is traceable - bulk recall over that lineage is specified and lands with M5.
"True until last month" is a first-class statement. Every relation can carry the interval it held in the world, separate from when the system learned it - so retroactive knowledge is captured the moment it arrives, and nothing is lost while the time-travel query logic (M3c) lands.
An open-world substrate: a miss comes back as
{found: false}, never conflated with "false", so an LLM
client cannot misread missing knowledge as negation. Asserting a
negation explicitly is the open half: it is what M3c's time-travel
queries wait on.
One process, one directory. A pure-Rust embedded B-tree (redb) holds
rows, graph edges, and vectors under ~/.supragnosis/redb.
No external database to run, and no C++ toolchain to build.
Ingest is free; promotion is gated. Changes to canon - tier promotions, entity merges, T-Box edits, recalls - flow through PR-like proposals, and a proposal is itself an observation: signed, replayable, reviewed in the curation console.
A force-graph viewer streams entities, relations, proposals, and sync chatter live over SSE - served on an owner-only unix socket, never a TCP port. The macOS desktop app is a thin tray-resident shell over the same socket. Watch your agents learn.
start / stop / status /
restart with pidfile and logs under
~/.supragnosis - or let Homebrew keep it running with
brew services. stdio for MCP-client children,
loopback streamable HTTP for everything else.
06 / mcp surface
# stdio: the client launches supragnosis
# as a child process
claude mcp add supragnosis \
-- $(command -v supragnosis)
# or point at the background daemon over HTTP
supragnosis start
claude mcp add supragnosis \
--transport http http://127.0.0.1:7373/mcp \
--header "Authorization: Bearer $(cat \
~/.supragnosis/mcp.token)"
Alongside the tools, addressable resources: every search hit points back
at supragnosis://observation/{id} - raw text, provenance,
lineage - and each workspace exposes its graph,
hypergraph, and types as read-only resources.
Whoever holds an id can dereference it: no answer without a "where from".
07 / portability
Laptop, desktop, a VM that never sleeps - every machine your agents work on ends up holding the same graph. What travels is the observation log, never merged state, so nothing is flattened on the way out: ids are content addresses that survive the move, projection is deterministic so any delivery order converges, and every attestation is signed by the node that made it. The receiving node can therefore prove where a claim came from and still decide for itself how far to trust it - a wire claim that "a human confirmed this" never outranks what the transport can actually prove. Sharing is opt-in per workspace: nothing leaves a node you did not whitelist. Hub-and-spoke ships today; the replication primitive is topology-independent, so peer and hybrid meshes reuse it unchanged when they land.
Portability here is a checked property rather than a promise. The content-address, convergence, and re-key guards run in CI on every change to the engine, and a principle whose guard stops running is reported as unguarded instead of quietly passing - the same registry that publishes what this system does not do yet.
08 / status
Nothing on this page is aspirational. Everything under shipped is in the binary you can install today; everything under in flight is named and specified, and not written yet.
The roadmap keeps an honest record of what shipped and what is deferred - see architecture.md sections 12 and 14.
09 / get started
# desktop app, signed + notarized:
# pulls the server with it
brew tap ashon/tap
brew install supragnosis
# server / CLI only, kept running as a service
brew install supragnosis-server
brew services start supragnosis-server
# no homebrew? the one-line script installs
# to ~/.local/bin (arm64 / x86_64)
curl -fsSL https://supragnosis.dev/install.sh | sh# one-line script -> ~/.local/bin
# (x86_64, checksum-verified)
curl -fsSL https://supragnosis.dev/install.sh | sh
# or homebrew (server formula)
brew tap ashon/tap
brew install supragnosis-server
brew services start supragnosis-servergit clone https://github.com/Ashon/supragnosis
cd supragnosis
# fastembed = local ONNX semantic recall
cargo build -p supragnosis-cli --features fastembed
cargo test
Whichever route you take, supragnosis start brings up the
daemon: MCP on 127.0.0.1:7373 plus the viewer unix socket.
Prebuilt binaries ship keyword recall; the fastembed build adds local
semantic search. Curious how it is built? The design principles and the
hexagonal Rust workspace behind all of this live in
architecture.md.