Build Your Own Soul Vault

What You Are Taking Home

You do not need nine Macs, eight harnesses or a daughter to need a soul vault. If more than one tool, session or machine reads an agent's instructions and memory, you have the problem this quest was about: one identity, many readers, a few writers, and a failure mode where the agent quietly becomes a generic model. This lesson turns the quest into a checklist you can apply to an agent of your own, in the order Soul Vault learned it.

1. Write the First Invariant, Then Measure It

Name the failure you would rather stop than tolerate, in one sentence. Build a probe for it (one neutral question, a handful of checks, pass, fail or unavailable with cause) and record a baseline before changing anything. Your baseline will probably find something already broken.

2. Count the Readers

Run a census of every place that knows where your agent's memory lives: repositories, harness configs, schedulers, prompt stores, templates, copies on other machines. Rows carry locations and fingerprints, never contents. Unreadable is an error, not zero.

3. Freeze a Root

Define one base class whose public methods hold every rule (id validation, the identity load order, compare-and-swap, capability checks, a closed set of named errors) and whose underscore primitives are all a storage implementation may write. Pin it with a hash test and a version constant. Add tests that fail when a child overrides a template or a caller identifies a child.

4. Point, Do Not Path

Put the choice of implementation and the store's location in one versioned record that every reader already has, named by role, never by host. Give it a generation that only grows, remembered per machine. No default, no fallback; every malformed record is a named failure.

5. Identity Whole or Not at All

Render the full ordered identity into one artifact named by the hash of its bytes, keep per-session facts on a short card, and make every failure on the way a refusal written as instructions to the model. Adapt to each harness's hook contract, and make sure a hook failure blocks rather than degrades.

6. Every Write a Record

Revisions are content hashes; writes are compare-and-swap; every write carries a request id that remembers its answer and a reason. Pick one atomic commit point and order everything else around it with an intent that can undo. Hold changes made around the door instead of accepting or reverting them. Protect the one note whose loss would break a name, in the function every write passes through.

7. Many Machines, One Store

Readers elsewhere serve a note only when its bytes match the canonical manifest. When the canonical store cannot be reached, they may serve a copy they verified earlier, labeled offline with the cause; a copy that does not match is never served, and a note never verified is a named failure. Writes from elsewhere are one request applied by the store's own templates, with three outcomes: never left, left without an answer, answered. Readers that may only read get a scoped door that hides what they may not see.

8. Move Readers, Then Bytes, Then Prove

Move every reader to the door while the bytes stay put. Then ship code before configuration, search (never remember) for long-running consumers, seal, adopt without inventing history, prove identity on the new store before pointing at it, flip one field, verify, probe everything, and cold-start every consumer under the new record. Close the way back deliberately, keep the evidence.

9. Keep Proving It

Run the rare paths every day on the live system with fixtures that cannot touch real data, check the real identity too, prove the monitor can see a fault by injecting one, and alert on silence as well as on red. Give every test subject a unique marker so a wrong identity cannot pass for a right one.

And Keep It Small

Last, the rule that kept Soul Vault small enough to build and prove in two days: write down what it will not own, and add a subsystem only when a row in the failure table needs it. A soul vault is a manager, not a platform. The notes stay plain text that opens with every service stopped.

Code

A one-page design worksheet for your own soul vault·text

FIRST INVARIANT   one sentence: ______________________________________
PROBE             question: ____  checks: ____  baseline taken: [date]
CENSUS            surfaces: S1 ____ S2 ____ S3 ____  open rows: ____
ROOT              primitives: ____  templates: ____  CONTRACT_VERSION = 1, hash pinned
ERRORS            closed set: ____ names; unknown -> internal_error
IDS               scheme://<vault>/<path>, relative, NFC, no hidden segments
POINTER           repo: ____  schema: ____  generation: 1  role (not host): ____
IDENTITY          load order: 1 ____ 2 ____ 3 ____  whole/pointer rule: ____
BUNDLE            name = sha256(bytes)[:12]; card holds per-session facts
REFUSAL           "<agent> not loaded: <code>: <cause>" + STOP instructions
WRITES            CAS on sha256; request id + digest; reason; one commit point: ____
GUARD             outside changes: hold | apply via write | discard by: ____
PROTECTED NOTE    ____ (rule lives in: ____)
REMOTE            reads: manifest-verified, offline label; writes: one request, 3 outcomes
CUTOVER           readers first; code before record; consumers found by search; cold start after
CANARY            daily rare paths; fixtures outside real data; sensitivity faults: ____
WILL NOT OWN      ____, ____, ____

The smallest honest start: a door with a refusal (starter sketch)·python

import hashlib, json, sys
from pathlib import Path

REQUIRED = ["identity.md", "instructions.md"]
STOP = "\n\nSTOP. Do not answer as a generic assistant. Report the line above."

def refuse(code: str, cause: str):
    raise SystemExit(f"agent not loaded: {code}: {cause}{STOP}")

def load_pointer(path: Path) -> dict:
    try:
        rec = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError) as exc:
        refuse("pointer_unreadable", f"{path}: {exc}")
    if not isinstance(rec, dict) or rec.get("schema") != "my.agent-pointer.v1":
        refuse("pointer_schema_error", f"{path} is not a my.agent-pointer.v1 record")
    if not isinstance(rec.get("store"), str) or not rec["store"]:
        refuse("pointer_schema_error", f"{path}: store is missing")
    return rec

def bootstrap(pointer_path: Path) -> str:
    store = Path(load_pointer(pointer_path)["store"])
    parts = []
    for name in REQUIRED:
        try:
            parts.append((store / name).read_text(encoding="utf-8"))
        except FileNotFoundError:
            refuse("identity_document_missing", name)
        except (OSError, UnicodeDecodeError) as exc:
            refuse("identity_document_unreadable", f"{name}: {exc}")
    bundle = "\n\n---\n\n".join(parts)
    out = Path("bundles") / f"agent-{hashlib.sha256(bundle.encode()).hexdigest()[:12]}.md"
    try:
        out.parent.mkdir(exist_ok=True)
        out.write_text(bundle, encoding="utf-8")
    except OSError as exc:
        refuse("bundle_unsaved", f"{out}: {exc}")
    return f"[agent] identity loaded. Read {out} in full before any task."

if __name__ == "__main__":
    print(bootstrap(Path(sys.argv[1])))

Exercise

Fill in the design worksheet for an agent you actually run, then build the starter: a pointer record with a schema, a bootstrap that loads every required identity document or prints a refusal with STOP instructions, and a bundle named by its own hash. Break the pointer on purpose, start a real session, and confirm the agent stops and reports the line instead of answering. That run is your first probe receipt.

Hint

Keep the worksheet's last line honest. The list of what your vault will not own is what keeps it small enough to trust.