Fig. 04 · Personal project
Soulbound
A self-hosted AI companion with governed long-term memory that can explain why it believes anything.
- Project
- Soulbound
- Role
- Sole developer
- Period
- 08/2026 - present
- Context
- Personal project
- Stack
- Python · Hybrid retrieval · Embeddings · Voice · pytest · systemd
- Outcomes
- One validated path for every change to memory
- Answers grounded in, and explained by, what the owner actually said
- Every requirement tied to automated evidence - 60+ test files and 9 architecture decision records
Problem
Most AI assistants remember little, can change what they remember without saying so, and live on someone else’s servers. Soulbound is a private, self-owned companion meant to last: one continuous, owner-controlled record of a life, and reasoning over it, on a machine the owner controls.
Constraints
- Never silently lose or change memory. Every change must be validated and explainable.
- Single owner, local only. No dependence on any vendor’s continued existence.
- Consent before action. World-changing actions require explicit, scoped, expiring confirmation.
- Degrade, don’t fail. Missing parts reduce capability; they don’t break the system.
Architecture
The figure follows what the owner says - into memory, back out as a grounded answer, and into the world only with consent.
- 01
Everything stays on the owner's machine
Soulbound is a single-owner runtime. Interfaces, reasoning, memory and actions all run locally, so the record of a life does not depend on any vendor staying in business.
- 02
One path changes memory
The model may only propose an interpretation. A validation gate decides what is stored, revised or retained - there is exactly one memory-affecting path, and nothing routes around it.
- 03
Answers can explain themselves
Hybrid retrieval grounds each answer in what the owner actually said, so the companion can explain why it believes anything it tells them.
- 04
Acting on the world needs consent
Read-only capabilities run freely. World-changing ones run only after an explicit, scoped, expiring confirmation from the owner - and every act is recorded.
- 05
Degrade rather than fail
When a replaceable part is missing, Soulbound keeps working with less and says so - a diagnostic command reports every seam and what its absence costs. State is backed up on a schedule.
Read the diagram as text
Components
- Owner
- The single person the companion belongs to; they type or speak to it on their own machine.
- CLI · HTTP · voice
- The entry points - a command-line interface, a local HTTP server and a voice interface.
- Reasoning
- Interprets what the owner says and proposes a structured interpretation; it never changes memory directly.
- Validation gate
- The single memory-affecting path - validation, revision, classification, retention and authorisation are decided here.
- Long-term memory
- An owner-controlled record that is never silently lost or silently changed.
- Hybrid retrieval index
- Semantic and keyword retrieval over memory, used to ground every answer in what the owner actually said.
- Capabilities
- A small set of bounded primitives - read-only ones run freely, world-changing ones only after explicit confirmation.
- Action record
- Every act taken on the owner's behalf is recorded.
- Backups
- Scheduled backups of the companion's state, run as a system service.
Boundaries
- Owner's machine: Everything runs on a machine the owner controls, with no dependence on any vendor's continued existence. Contains CLI · HTTP · voice, Reasoning, Validation gate, Long-term memory, Hybrid retrieval index, Capabilities, Action record, Backups.
Flows
- Something the owner says is remembered: Owner → CLI · HTTP · voice → Reasoning → Validation gate → Long-term memory.
- An answer grounded in memory: Long-term memory → Hybrid retrieval index → Reasoning → CLI · HTTP · voice → Owner.
- An action is taken and recorded: Reasoning → Capabilities → Action record.
- The owner confirms a world-changing action: Capabilities → Owner.
- State is backed up: Long-term memory → Backups.
Key decisions & trade-offs
One memory-affecting reasoning path
The model may propose a structured interpretation, but validation, revision, classification, retention and authorisation are decided by a gate and the memory subsystem. Every mode traverses the same gates, and nothing routes around them.
The simpler design lets the model write memory directly. I rejected it because memory would then change in ways nobody could audit or explain, and one bad generation could quietly rewrite what the system believes.
Evidence over assertion
Requirements live in a register, and the progress tracker is generated from that register plus a live test run - a requirement cannot be marked complete by editing a cell, and a skipped test counts as missing evidence.
A conventional backlog was lighter, but it lets work be marked done on someone’s word. The cost is overhead: every requirement needs a test before it can count, which slowed early progress in exchange for a status that cannot drift from reality.
Results
- One continuous, owner-controlled memory with a single validated path for change.
- Answers grounded in retrieval over what the owner said, able to explain their basis.
- Over 60 test files, 9 architecture decision records and 37 dated experiment records.
Soulbound is under active development as a sole-author project, with continuous integration on every change.
What I’d do next
- Owner-directed erasure - the repository’s next open decision - so forgetting is as governed and explainable as remembering.
- Measure retrieval quality against the experiment records instead of spot checks.