Observations are the truth
Knowledge arrives as immutable observation events: append-only, provenance-preserving. The entity/relation graph is a deterministic projection of the log. Replay the log anywhere and the same graph materializes.
supra (above) + gnosis (knowing)
Knowledge
above knowledge.
supragnosis is an embedded, file-based knowledge server written in Rust. It structures what your agents learn across hosts and workspaces into an ontology - a living concept/relation graph - and serves it to any MCP client.
install
curl -fsSL https://raw.githubusercontent.com/Ashon/supragnosis/main/scripts/install.sh | sh
- v0.1.6
- Rust
- MIT OR Apache-2.0
- macOS arm64 / x86_64
- Linux x86_64
01 / core ideas
Three commitments, held everywhere.
Local-first, topology-free
Local-only, central hub, direct peer, or hybrid: every connection topology converges without conflict under the same merge semantics. Events are ed25519-signed and replicated over TLS.
Swappable by construction
A hexagonal core with zero IO. Stores, embedders, and extractors are ports with adapters: CozoDB today, Oxigraph tomorrow, in-memory for tests. The domain never notices.
02 / how it works
From observation to ontology.
observeMCP tool call
->
observation logimmutable, signed
->
projectordeterministic
->
ontologyentities + relations
->
recallsearch / traverse / map
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.
03 / capabilities
Small binary, serious semantics.
Hybrid recall
HNSW vector search over local ONNX embeddings (fastembed), fused with keyword search. Ranking is deterministic; without embeddings it degrades gracefully to keyword.
Embedded, file-based
One process, one directory. CozoDB on RocksDB unifies relational,
graph, and vector under ~/.supragnosis/db. No external
database to run.
Proposal gate
Changes to canon - tier promotions, merges, T-Box edits, recalls - flow through PR-like proposals with a curation console.
Provenance and trust
Every fact carries host, workspace, delegation chain, and trust tier. Contaminated sources can be quarantined and recalled in bulk, even across the federation.
Live ontology viewer
A loopback-only web viewer streams entities, relations, and sync chatter as they land. Watch your agents learn.
Self-managed daemon
start / stop / status /
restart with pidfile and logs under
~/.supragnosis. stdio for MCP-client children,
streamable HTTP for everything else.
04 / mcp surface
Speak MCP, remember everything.
# stdio (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- observe
- load knowledge: entities, relations, and text become observation events
- search_knowledge
- semantic + keyword hybrid recall, deterministically ranked
- get_entity
- one entity with its relations and full provenance
- traverse
- n-hop walks over the relation graph
- workspace_map
- co-occurrence contexts (hyperedges) across a workspace
- and more
- federation (sync_*), proposal, and curation tools - 13+ in total
05 / federation
Any topology. Same graph.
Hosts replicate observation logs, not merged state. Because projection is deterministic and merge semantics are shared, hub-and-spoke, peer-to-peer, and hybrid meshes all converge to the same ontology. Node identity is an ed25519 keypair; events are signed and shipped over TLS with per-node auth.
06 / inside
A workspace of eight crates.
coredomain models + ports, zero IO
storeCozoDB and in-memory adapters
engineingest, projection, query, sync
embedfastembed / hashing / none
syncidentity, signing, replication
mcprmcp tools, resources, prompts
vizlive ontology viewer
clithe supragnosis binary
07 / status
Where it honestly stands.
- [o]M2 - hybrid recall. Semantic (fastembed ONNX) + keyword search, Cozo persistence, stdio MCP + HTTP daemon.
- [o]M3.5 - proposal gate. PR-like curation console for promotions, merges, T-Box changes, recalls.
- [o]M4 phases 0-4 - federation. Hub-and-spoke log replication, ed25519-signed events over TLS, per-node auth, federated recall.
- [ ]M3 - resolution layer. Not started: entity identity is still exact canonical-name match.
- [ ]M5 / M6. Extraction + contamination logic, forgetting + consolidation.
The roadmap keeps an honest record of what shipped and what is deferred - see architecture.md sections 12 and 14.
08 / get started
Up and running in a minute.
# macOS (arm64 / x86_64), Linux (x86_64)
# installs to ~/.local/bin with checksum verification
curl -fsSL https://raw.githubusercontent.com/Ashon/supragnosis/main/scripts/install.sh | sh
supragnosis start # daemon: MCP :7373 + viewer :7374
supragnosis status
supragnosis stopgit clone https://github.com/Ashon/supragnosis
cd supragnosis
# includes local ONNX semantic search
cargo build -p supragnosis-cli --features fastembed
cargo test