Case study / Interpretable Context Methodology
SOUL ICM Second Brain
A source-backed operating brain, not a chatbot
SOUL ICM is a file-native operating system for context: it makes the path from incoming evidence to approved, reusable knowledge visible, bounded, and reviewable.
Published · Updated
Why this exists
Most AI projects start with a model and end with a prompt. SOUL starts with the work: the sources, decisions, constraints, people, and approval points that make an answer safe to use.
The goal is not to build an AI that knows everything. It is to build a system that can show what it knows, where the context came from, what it is allowed to use, and when a person must decide.
Operating model
The system treats context as a governed path, not a pile of documents. Each stage leaves an inspectable artifact for the next one.
Architecture at a glance
Deterministic routing from incoming evidence to approved, reusable context. Click a step to expand.
Intake
An incoming request or source is classified, bounded, and routed to the one workspace authorized to handle it.
Source register
Sources carry stable identifiers, classification, ownership, review dates, and enough provenance to support later checking.
Workspace route
Company direction, delivery, governance, technology, and other workspaces keep retrieval narrow and explainable.
Verified knowledge
Lookup returns source-backed, approved context from the selected vault and explicitly abstains when the evidence is not sufficient.
SOUL layer
The Company Soul and isolated Client Souls organize value, decisions, signals, and proposed learning without silently changing authority.
Founder review
A human approves durable truth, publication, transfer, or generalization. The system records what changed and why.
Design decisions
Context contracts over prompt conventions
Choice. Routing lives in concise AGENTS.md, CONTEXT.md, and stage contracts.
Why. A person can inspect the route, inputs, checks, outputs, and stop conditions without reverse-engineering hidden agent state.
Tradeoff. The system takes more deliberate setup than a broad prompt, but the operating path stays repeatable and auditable.
File-native first, retrieval second
Choice. Plain Markdown, explicit metadata, and deterministic lookup form the control surface before adding a vector service.
Why. The company can review, version, validate, and use the same context in Obsidian or with model-agnostic agents.
Tradeoff. The first search layer is intentionally narrow and inspectable; more sophisticated retrieval can be added only when the work proves it is valuable.
Physical client isolation over tags alone
Choice. Each client vault is a separate repository with its own boundary; the corporate registry stores routing metadata, not client knowledge.
Why. A label can be ignored. A separate vault makes cross-client leakage harder to create and easier to detect.
Tradeoff. Cross-client reporting requires an approved, redacted projection instead of convenient direct search.
Human authority over autonomous memory
Choice. Agents may collect, transform, analyze, check, and draft; humans approve durable truth and external delivery.
Why. Accountability, scope, and customer trust remain explicit instead of being inferred from model output.
Tradeoff. Some decisions move more slowly, but an abstention or review is safer than a confident, unowned answer.
System components
Corporate vault
A file-native operating brain with routed workspaces, source registers, and explicit information-classification rules.
ICM validators
Deterministic Python checks for structure, metadata, provenance, scope, review state, and client-boundary safety.
Verified knowledge lookup
Searches one explicitly selected vault for source-backed knowledge and abstains when context is missing, stale, conflicting, or unauthorized.
Client-vault boundary
Opaque-ID client repositories keep client context separate from the corporate brain and from every other client.
What exists today
This is an in-progress build. These are the capabilities and checks present in the worktree, not claims of a completed client deployment.
Deterministic vault validation
Vault and Soul validators check structure, scope, metadata, provenance, classification, review dates, approval state, and boundary contracts mechanically.
Source-backed knowledge lookup
The lookup tool accepts one explicitly selected vault and searches routed knowledge for verified notes, returning source IDs and review state rather than unqualified text.
Governed Soul records
Signals, hypotheses, experiments, improvements, pulses, metrics, and outcomes use stable IDs and explicit authority so proposed learning can be reviewed before promotion.
Synthetic acceptance coverage
A disposable acceptance runner exercises onboarding, client-boundary locality, redacted portfolio projection, founder-brief metadata boundaries, and mechanical improvement gates without using real client data.
Governance safeguards
- Founder approval is required for durable knowledge, publication, and generalization
- Client content stays in its client vault; only approved, redacted learning can move upward
- Agents and contributors prepare and validate work but cannot approve or own truth
- Missing, stale, conflicting, or unauthorized context produces abstention or escalation
Boundaries by design
- This is not a chatbot with a larger memory. It is an operating contract for context, evidence, routing, and review.
- Credentials, API keys, client-confidential material, and deliverables do not belong in the corporate repository.
- Real client data is excluded from scaffolding and validation until the trust-boundary work is complete and founder-approved.
- Markdown contracts declare how work must be handled; they do not grant Windows filesystem permissions or replace access controls.
- When evidence or authority is missing, stale, conflicting, inaccessible, or unauthorized, the correct result is abstention or escalation.