Skip to content
SHAMPOO

Manual · Chapter 3 of 19

SHAMPOO architecture

All chapters

SHAMPOO architecture

The three binaries

Component Runs Does
saphira-memoryd central host Authoritative service: tools and their semantics, authentication and authorisation decisions, project scope, persistence, orchestration. The sole database client.
saphira-memory-spoke every workstation Thin local adapter: presents MCP stdio to the assistant, owns the bootstrap secret, shakes hands, renews sessions, forwards everything sealed to central. No database, no SQL, no authority decisions.
saphira-memory-pump central host Mechanism only: materialises recurring timers, drains delivery jobs, retries with backoff. It transports facts; it never decides direction or agreement.

Implementation names stay as they are; the product surface is SHAMPOO Memory MCP. A conformance rule keeps the spoke thin: remove the central daemon and the spoke becomes useless: every call fails clean, because no answering logic lives in it.

One endpoint, many boundaries

OpenCode / Codex / Claude Code
  -> local MCP stdio (loopback only)
  -> saphira-memory-spoke --serve --endpoint https://HOST/mcp --profile NAME
  -> HTTPS (outer transport) + SHAMPOO sealed envelope (inner, mandatory)
  -> central saphira-memoryd (one listener)
  -> loopback database (per-profile databases)

One listener serves every profile. The requested profile travels in the handshake; the credential check runs against that profile's own grants; the opened session is bound to that profile permanently. There is no cross-database fan-out, no merged search, no central authentication router: profile authority stays profile-local by construction.

Network and trust flow

  1. The spoke resolves the endpoint (DNS/IPv6), validates TLS against system roots (plus --ca-file where private anchors are needed), and opens HTTPS. TLS is mandatory but is not the payload-protection boundary.
  2. Inside TLS, every request and response travels in the SHAMPOO sealed envelope (hybrid ECDH P-256 + ML-KEM-768, HKDF-SHA-512, AES-256-GCM, per-message nonces, direction- and session-bound). The daemon rejects unenveloped traffic: a generic client speaking plaintext cannot connect. The spoke is required local infrastructure, not an option.
  3. Authentication rides the envelope: bootstrap handshake once, then short-lived session credentials, renewed on a deterministic jittered schedule (about 42–48 minutes) with bounded backoff. No database credential ever leaves the central host; workstations hold only client identity plus renewable session material.

There is no SSH in the client trust path. SSH may move bundles and packages between operator machines; it never carries memory traffic.

TLS versus SHAMPOO authentication

Two different jobs, often confused:

  • TLS proves the workstation reached the real endpoint and encrypts the transport. It says nothing about who may read or write.
  • SHAMPOO bootstrap/session/profile binding proves which principal, which profile, and which projects, per call, against live grants, with revocation effective on the very next operation.

Auth: Unsupported in the MCP capability advertisement concerns only the generic MCP transport-auth mechanism, which SHAMPOO does not use. The platform is fully authenticated one layer up, in the spoke/daemon plane described here. See 12-authentication-and-enrolment.

Sessions and connections

One profile per connection and session: two boundaries means two spoke processes, two TLS connections, two independent sessions (possibly sharing one client_id string where it is enrolled in both). Closing or killing a session affects exactly that connector. Sessions expire hourly and renew transparently; a session credential replayed against another profile, or after revocation, denies generically. See 06-context-and-sessions and 03-security-and-boundaries.

On this page