sapere-server 0.1.0

Sapere — governed memory for AI agents. The product layer (door-1 REST + MCP) over the prodedify-memory engine, deployable standalone or mounted by a host (ADR-015).

sapere-server

Sapere — governed memory for AI agents, standalone. The door-1 REST surface (propose → govern → ground → replay), the MCP surface, and a tamper-evident audit chain over the prodedify-memory engine — one container, one Postgres, native hashed API keys. No IdP, no vendor cloud callback (ADR-015).

Quickstart (≈10 minutes, Docker Compose)

cd deploy/
docker compose up -d --build          # pgvector Postgres + the server; engine schema migrates to head

# 1. Mint a workspace API key — the secret prints ONCE and is never stored
docker compose exec server sapere-server keys mint \
  --workspace 11111111-1111-1111-1111-111111111111 --name my-first-key
export SAPERE_KEY=sk_sapere_...        # from the mint output

# 2. Propose a fact — it lands PROPOSED (fail-closed; humans promote)
curl -X POST localhost:8010/api/v1/sapere/v1/facts \
  -H "Authorization: Bearer $SAPERE_KEY" -H 'Content-Type: application/json' \
  -d '{"summary":"We only quote on properties with certified wiring","detail":"Underwriting guideline v3 §2.1"}'

# 3. See the review queue
curl -H "Authorization: Bearer $SAPERE_KEY" localhost:8010/api/v1/sapere/v1/pending

# 4. Ground — an audited, hash-chained snapshot of what counts right now
curl -X POST localhost:8010/api/v1/sapere/v1/ground \
  -H "Authorization: Bearer $SAPERE_KEY" -H 'Content-Type: application/json' \
  -d '{"query":"wiring"}'
# → note audit.audit_id in the response

# 5. Replay it — the demo moment: VERIFIED means the served set reproduces
curl -X POST localhost:8010/api/v1/sapere/v1/audit/<audit_id>/replay \
  -H "Authorization: Bearer $SAPERE_KEY"

deploy/quickstart_litmus.sh runs this whole lifecycle end-to-end (and tears the stack down).

MCP (door 2). With SAPERE_MCP_ENABLED=true (the compose default) the MCP endpoint at /api/v1/sapere/mcp accepts the same sk_sapere_… keys — tools: ground, retrieve, propose, replay, pending. There is deliberately no promote tool: agents propose, humans decide. Have an IdP? Point SAPERE_MCP_JWKS_URL at its JWKS to also accept your JWTs.

Production posture

• BYO Postgres 16+ with pgvector + pg_trgm (the bundled DB is the eval/dev default). Set SAPERE_SERVER_DATABASE_URL; run sapere-server migrate as a gated step (SAPERE_SERVER_MIGRATE_ON_START=false).
• Connect as a NOBYPASSRLS role so the engine's FORCE-RLS tenancy is a real control, not decoration.
• Recall embedder (optional): SAPERE_OPENAI_API_KEY enables semantic recall; without it retrieval degrades gracefully to lexical + entity + recency. SAPERE_REQUIRE_EMBEDDER=true makes a missing key a loud 503 at the write boundary instead of silent under-recall.
• Document ingest returns 501 on this worker-less core; the ingest worker profile ships separately.
• No rate limiting is built in yet — put the server behind your gateway's limiter for now.

Keys

sapere-server keys mint --workspace <uuid> [--name N] [--expires-days D]
sapere-server keys list --workspace <uuid>
sapere-server keys revoke --workspace <uuid> --key-id <id>

Keys are stored as SHA-256 hashes (256-bit secrets, shown once); revocation and expiry are set-columns — a key's lifecycle stays auditable, never deleted. A key's writes are stamped with its own source identity and land PROPOSED unless that exact identity has been explicitly trusted in write_policy.

Embedding in your own app

pip install sapere-server and mount the same router your way: implement the SapereHost seams (sapere_server.hosting) — sessions/tenancy, key context, workspace anchors, ontology registry — and include_router the surface. The hosted Prodedify backend consumes this exact package through those seams, with parity tests pinning that both deployments serve the same product.