sis-memory-orchestrator

Files (6)

• SKILL.md
• benchmarking-protocol.md · references/
• privacy-hardening.md · references/
• subagent-roster.md · references/
• substrate-matrix.md · references/
• benchmark_substrates.py · scripts/

SKILL.md (first lines)

# 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)

From frankxai/Starlight-Intelligence-System, MIT.

More from frankxai/Starlight-Intelligence-System