sis-memory-orchestrator

SIS Memory Orchestrator

v0.1 scope cut (2026-04-30) — round-trip-first.

This skill describes the full architecture. What ships in v0.1 is a deliberately small subset: 3 agents (Router, Guardian, Bencher), 2 substrates (mempalace in-tree adapter + Qdrant scaffold-disabled), replay-only benchmarks, dog-fooded through People Intelligence /perf-feedback-rehearsal. Implementation lives in private/voice-operator/service/memory/. CLI surface: python -m service.memory.cli {commit,recall,status}.

The remaining agents/substrates/cron/encryption/CRDT below are parked with falsifiable un-park triggers in memory/benchmarks/DECISIONS.md. A parked item ships only when its trigger is observed on the live system — not from a roadmap.

The v0.1 success gate: a /perf-feedback-rehearsal write reaches mempalace, a follow-up recall() returns it, Guardian blocks a PII probe, audit log records the full sequence — all green on Frank's machine before this commit (d9cc95b) is pushed.

Plan: docs/superpowers/plans/2026-04-30-sis-memory-orchestrator-v0.1.md.

Synthesizes the best memory patterns from across the field into one substrate-agnostic orchestration layer for SIS:

• mempalace — episodic / semantic / procedural split, embedding-indexed, hot/warm/cold decay
• Letta (MemGPT) — hierarchical agent memory with self-edit
• Anthropic Claude Code team — CLAUDE.md as canonical entry, auto-memory atoms with WHY/HOW
• Karpathy / Hashimoto — code-as-handover, ADRs over prose, structured state replaces sprawl
• Geoffrey Litt (malleable software) — ownership stays local; CRDTs for sync
• Ink & Switch local-first — privacy by architecture, not policy

When this skill fires

• User says: SIS memory / where does X capture go / memory substrate / mempalace / Letta / Mem0 / AgentDB / "swap memory backend" / "benchmark substrates" / "memory privacy" / "leak audit"
• New sovereign forking SIS (/sovereign-spawn) — auto-runs the substrate selector for them
• Periodic (weekly): runs benchmark + decay sweep
• On capture/packet write: validates write hits the right substrate, fires Privacy Guardian

Core workflow

Every memory operation flows through five gates. Pick which agents to dispatch by operation type — the routing table is below.

                           ┌─────────────────────────┐
   user / agent ──────────▶│  1. Privacy Guardian   │ ← redact PII, enforce policy
                           └────────────┬────────────┘
                                        │
                           ┌────────────▼────────────┐
                           │  2. Substrate Selector  │ ← pick mempalace / Letta / vault MD / KG JSONL
                           └────────────┬────────────┘
                                        │
                           ┌────────────▼────────────┐
                           │  3. Indexer / Retriever │ ← write or query
                           └────────────┬────────────┘
                                        │
                           ┌────────────▼────────────┐
                           │  4. Graph Maintainer    │ ← cross-ref, deduplicate
                           └────────────┬────────────┘
                                        │
                           ┌────────────▼────────────┐
                           │  5. Auditor             │ ← attestation chain, leak audit
                           └─────────────────────────┘

Subagent team — pick the size

Tier	Agents	When
Minimal (3)	Indexer · Retriever · Privacy Guardian	Single-user, single-substrate, trust-this-machine
Production (7)	+ Graph Maintainer · Substrate Benchmarker · Decay Manager · Auditor	Default for adopting SIS; weekly benchmarks; multi-substrate
Advanced (10)	+ Council Convener · Cross-Project Sync · Health Monitor	Multi-tenant / cross-machine / SaaS deployment

Agent contracts: see references/subagent-roster.md.

Substrate selection — first decision

Default for new adopters: filesystem markdown + JSONL knowledge-graph + local Qdrant — covers 80% of use cases, requires zero external services, fully sovereign.

When to add or swap:

Symptom	Add this substrate
"Find captures by meaning, not keyword"	mempalace OR Qdrant + sentence-transformers (local)
"Memory grows beyond 10k entries, retrieval slow"	mempalace OR Letta with hot/warm/cold decay
"Need self-editing memory across long agent sessions"	Letta (MemGPT)
"Need agent-as-a-service style memory layer"	Mem0
"Continuous screen capture for ambient context"	screenpipe
"Sub-50ms recall in voice path"	AgentDB (singleton daemon, see constraint below)
"Multi-tab agent with shared memory"	Memory Bus daemon — see constraint below

Hard constraint (memory): AgentDB and most embedded vector DBs spawn one process per connecting tab. At ~10 tabs the system breaks (per project_agentdb_singleton_constraint.md). All multi-process memory architectures MUST front through a singleton daemon (MCP server, Windows Service, or FastAPI). The voice-operator FastAPI :7373 already serves this role for the cognition loop.

Full matrix with install paths, latency profiles, license terms, leak posture: see references/substrate-matrix.md.

Privacy posture (non-negotiable)

This is what makes the system safe for anyone adopting SIS, not just Frank.

1. Everything local by default. mempalace, Qdrant, Letta — all run as local Docker / Python processes. Nothing leaves the machine without explicit user action.
2. Embeddings local too. Use sentence-transformers (all-MiniLM-L6-v2 for speed, bge-large-en-v1.5 for quality) — never OpenAI/Cohere embedding APIs that ship vault content over the wire.
3. PII redaction before any external call. Privacy Guardian runs FIRST. Before any payload goes to OpenRouter / Anthropic / fal.ai / etc., scan for: emails, phone numbers, addresses, API keys, person names mentioned in private vault entries. Redact or block.
4. Encryption at rest (optional, opt-in): vault MD files encrypted with age (yubikey-backed) for sovereign tier.
5. Audit log of every read/write. memory/_audit/{date}.jsonl records who/what/when/source — Auditor scans this for anomaly patterns.
6. No cross-tenant bleed. Each sovereign user gets their own substrate namespace; the orchestrator enforces isolation via path prefixes + DB schemas.
7. Adversary model: assume an LLM call could exfiltrate context. Redact secrets BEFORE adding to context. Never include full vault content in agent system prompts; retrieve top-k slices only.

Full threat model + redaction patterns: see references/privacy-hardening.md.

Benchmarking protocol

Quarterly (or on substrate add): run the bench suite against the user's actual corpus.

Metrics:

• recall@k (k=5) — given known queries, does the right entry surface in top 5?
• latency p50 / p95 — wall-clock ms per retrieval
• leak risk — does any retrieval surface PII not in the query scope?
• cost — $ per 1k retrievals (relevant for cloud substrates)
• footprint — disk + RAM at 10k / 100k / 1M entry scale

Run via scripts/benchmark_substrates.py. Results write to memory/benchmarks/{date}.json and a one-page summary in memory/benchmarks/RECOMMENDATIONS.md (auto-updated by the Substrate Benchmarker subagent).

Full protocol: see references/benchmarking-protocol.md.

Mempalace install (recommended starter)

When a user asks "set up mempalace":

1. Verify clone + Python 3.11+: git clone https://github.com/mempalace/mempalace ~/.starlight/mempalace
2. Install: cd ~/.starlight/mempalace && pip install -e . (or follow upstream README)
3. Register in SIS: append to private/voice-operator/config/substrates.toml:

   [substrates.mempalace]
   enabled = true
   path = "~/.starlight/mempalace"
   embedding_model = "all-MiniLM-L6-v2"   # local, no external API
   tier = "warm"
   

4. Migrate existing knowledge-graph entries: python -m service.memory.migrate --from kg-jsonl --to mempalace
5. Run benchmark: python skills/memory/sis-memory-orchestrator/scripts/benchmark_substrates.py --substrate mempalace
6. Privacy Guardian audits the migration; Auditor re-attests every imported entry.

If upstream mempalace API differs from the contract above, update references/substrate-matrix.md::mempalace section with the actual contract.

What this skill produces

When dispatched:

• For a write op: the substrate decision + the redacted payload + the attested entry path
• For a read op: top-k slices from each enabled substrate, ranked by relevance + recency
• For a benchmark op: a one-page recommendation table
• For a leak audit: the redacted-or-quarantined entries report
• For an adoption op (new sovereign): a substrate plan + the install command list

When NOT to fire this skill

• Routine commit / docs / one-off code fix — no memory op
• User explicitly says "don't touch memory"
• The 6 v6 commands (/council, /navigate, etc.) handle their own memory writes via existing skill auto-activation — don't double-dispatch

Reference files

• references/substrate-matrix.md — every supported substrate: install, contract, latency, license, leak posture
• references/subagent-roster.md — 7 (or 3 / 10) agent contracts: signatures, when to dispatch, what they return
• references/privacy-hardening.md — full threat model, redaction patterns, anti-leak architecture
• references/benchmarking-protocol.md — metrics, harness, hypothesis test design

Coupling to existing SIS

This skill does not replace existing memory plumbing. It coordinates it.

• Existing memory/vaults/*.md — kept; this skill treats them as the cold-tier filesystem substrate
• Existing memory/knowledge-graph/index.jsonl — kept; warm-tier append-only log
• Existing memory/voice-sessions/{date}.md — kept; hot-tier daily capture log
• Existing brain-graph / brain_watchdog — kept; this skill is upstream of it

Adding mempalace / Letta / Qdrant means augmenting, not replacing. The orchestrator routes to the right tier per op.