The state layer
What Sophia actually is, a single local daemon that turns your documents, code, and agent observations into durable, queryable state.
03 / REFERENCE
System
reference.
SOPHIA / State Operating Platform for Human Intelligence Agents
Mechanisms, guarantees, and boundaries. Each topic is checked against product source at a pinned revision.
Foundations
What the record is made of: artifacts, claims, evidence, and the graphs over them.
The knowledge graph
How Sophia turns mined and remembered claims into typed, entity-scoped, provenance-carrying rows an agent can filter and join instead of re-reading source text.
Truth and provenance
A claim only lands in the graph if its evidence is a literal substring of the source, disagreeing claims surface through a query instead of a scroll-back, and a correction you make outranks the model structurally, not by convention.
The time machine
Every insert, update, and delete against your data lands in an append-only journal first, so a single mutation (or an entire agent session) can be inspected and, in most cases, undone.
Working with it
What an agent actually calls, session by session: the tools, the queues, the coordination.
The MCP surface
Sophia is the MCP server your agent talks to; every tool it sees is sophia.*, discoverable at runtime by capability family, with a sandboxed execute_code isolate for composing several reads into one round trip.
Search and retrieval
sophia.search is the one cross-corpus front door (structured rows, document-body hybrid search, and wiki near-title matching in one call), with an intent parameter that re-routes to a specialized tool once you know which corpus you want.
Multi-agent coordination
Two agents sharing a project post to typed channels and read a per-connection inbox, with server-resolved sender and target identities, bounded structured payloads, and a per-channel sequence that makes ordering checkable.
Mining
How a document or code module becomes typed graph facts, through durable queues and time-boxed leases that a self-refilling pipeline keeps stocked, and a work-order façade that collapses a ten-call setup ceremony into one.
Deterministic change intelligence
When a repository changes, Sophia first makes a deterministic freshness decision (unchanged, targeted delta, or full re-mine), then keeps uncertainty visible instead of silently treating old summaries as current.
The codebase graph
Tree-sitter parses a linked repository locally into modules, symbols, and edges, so a coding agent finds a definition, walks its neighborhood, and reads its source in four typed calls instead of a round of file globbing.
The wiki
Every entity gets one system-seeded canonical wiki page (plain markdown on disk, Obsidian-native, indexed for fast reads), and an owner can attach their own existing vault alongside it as a read-through add-on that never gets rewritten into the canonical index.
Memory across sessions
A new agent connection recovers where the last one left off through a small family of explicit calls (orient, catch_up, brief_me, saved session pages, an acknowledged-corrections loop, in-DB skills, and a persistent goal stack), not through anything that happens automatically.
Launching a managed agent
A managed launch runs an owner-approved plan end to end: the daemon verifies the pinned harness binary it is about to run, builds a private single-credential config home for the session, delivers the agent's bearer over a one-use local socket instead of argv or environment, and supervises the whole thing as a systemd unit whose terminal you can attach to without gaining any Sophia authority.
Guarantees
What the owner can rely on: custody, permissions, provenance, and the limits stated plainly.
The trust covenant
Five guarantees about how the daemon treats your data (local-first with separately opt-in contribution, quote-grounded truth, reversible writes, scoped access with an elevated-write approval gate, and no silent provider fallback), each one a specific code path, not a policy statement.
The security model
Every agent connection is minted deliberately by the owner (or, for delegated workers, by a connection the owner already trusted), carries a profile and an entity scope enforced at the query layer, and reaches a fixed set of elevated writes through one approval gate no profile can skip.
Skills and instruction trust
Sophia treats skills as a governed instruction supply chain: owner-gated publication, compiled cross-harness workflows, final-byte installation receipts, and an explicitly unattested runtime signal that never widens agent authority.
Your data, your contribution
Sophia can keep a configurable local record of its own work for you, while diagnostics and training contribution remain separate, default-off choices with an inspectable scrubbed payload.
Integrity seals and guarded restart
Tamper-evident seals over the record, one write chokepoint that refuses until integrity is proven, and a guarded restart that passes the same verification gate as a crash: deliberate maintenance gets no privileged path.
Evidence envelopes and the action gate
An envelope binds a claim to the actor, the authority it held at admission, the evidence it relied on, and the context it was actually given, so a consequential action is admitted or refused on the record rather than on an agent's say-so.