Releases: qbtrix/soul-protocol
v0.4.0 — Identity bundle
The identity bundle release. Multi-user souls, user-defined memory layers + domain isolation, and a verifiable Ed25519-signed trust chain. Plus rolled-in polish: density-driven focus, memory update primitives, and a wiki rebuild.
Identity bundle
- Multi-user soul support (#46) —
soul.observe(user_id=...)andsoul.recall(user_id=...)filter memory and bond context per user.BondRegistrytracks per-user relationship strength. Lazy creation of per-user bonds keeps single-user souls free of overhead. CLI:soul observe --user,soul recall --user, per-user bonds insoul status. MCP:soul_observe(user_id=...),soul_recall(user_id=...). - User-defined memory layers + domain isolation (#41) —
MemoryTypegraduates to open string layers. NewMemoryEntry.domainfield for namespacing (finance,legal,personal, ...).MemoryManager.layer(name)returns aLayerViewfor arbitrary layer names. Newsociallayer for relationship memory.DomainIsolationMiddlewaresandboxes a soul to a domain allow-list; reads filter, writes raiseDomainAccessError. CLI:soul remember --domain,soul recall --layer/--domain, newsoul layerscommand. Persistence stays flat for default-domain souls; nestedmemory/<layer>/<domain>/entries.jsonlayout used only when needed. - Trust chain — verifiable action history (#42) — every learning event, memory mutation, evolution step, and bond change appends a signed entry.
TrustEntrycarries the action, a payload hash (not the payload),prev_hashfor the Merkle-style chain, and an embedded public key per entry so verification works without an external registry. DefaultEd25519SignatureProviderships inruntime/crypto/.Soul.verify_chain()is bound to the loaded keystore's public key — shared souls (include_keys=False) cannot be impersonated by chain replacement. New CLIs:soul verify,soul audit. Full threat model indocs/trust-chain.md.
Rolled-in polish
- Density-driven focus (#194) —
SoulState.focusis computed from a sliding window of recent interactions instead of being a static default. Manual lock viasoul.feel(focus="<level>");feel(focus="auto")clears the lock.Soul.recompute_focus(now)for read-time freshness. - Memory update primitives (#193) —
Soul.supersede()writes a new memory and links the old viasuperseded_by.Soul.forget_one()for audited single-id deletion. New CLIs:soul supersede,soul forget --id. Fixes a stale bug wheresoul forgetreported 0 memories on successful deletion. - Wiki rebuild (#186) — fresh wiki regeneration covering 328 articles.
Schema migrations
Existing .soul files load cleanly. Migration is automatic on awaken.
MemoryEntrygains optionaluser_id: str | None = Noneanddomain: str = "default".- Memory layout migrates from flat to nested only when a soul uses non-default domains or non-standard layers.
trust_chain/andkeys/directories created on first signed action.- Legacy souls with
bonded_toset auto-populate a defaultBondTargeton awaken.
Breaking changes
MemoryTypeisstr-typed at the spec layer. Runtime StrEnum still compares equal to its string values, so most code is unaffected.Soul.observe(*, user_id=None, domain="default")andSoul.recall(*, user_id=None, layer=None, domain=None, ...)add keyword-only filters. Default behavior unchanged when filters are omitted.Soul.export(*, include_keys=False)defaults to excluding the private signing key. Sharing a soul preserves verifiability without giving away signing power.
Tests
2551 passing. New: 11 multi-user, 46 memory layers, 79 trust chain, 4 pubkey-binding (added in security review).
Closes
- #46 (multi-user soul support)
- #41 (memory layers + domain isolation)
- #42 (trust chain)
- #183 (0.4.0 release tracker)
What's next
v0.3.4 — packaging hotfix
Hotfix for the 0.3.3 wheel upload. No new features, no behavior changes — if pip install soul-protocol==0.3.3 already worked for you (it did, via the sdist), you don't need to rush this one.
Headlines
- Wheel uploads to PyPI again. The 0.3.3 wheel shipped the bundled template YAMLs twice (once through hatchling's package walk, once through a redundant
force-includeinpyproject.toml), so PyPI rejected the archive. This release drops the duplicate include. Templates still ship, once.
What went wrong on 0.3.3
pyproject.toml had a leftover [tool.hatch.build.targets.wheel.force-include] block pointing at src/soul_protocol/templates. Those files already land in the wheel via the default package walk, so the force-include produced a second copy of each YAML and a ZIP with duplicate filenames. PyPI refused it:
400 Invalid distribution file. ZIP archive not accepted: Duplicate filename in local headers.
The source distribution uploaded fine, so pip install soul-protocol==0.3.3 still worked — pip fell back to the sdist. Wheel installs only got the fix here.
Why 0.3.4 and not a re-cut of 0.3.3
PyPI doesn't let you re-upload a version, even after a manual delete. Bumping forward was the only way out.
Tests
2371 passed, 4 warnings
Upgrade
pip install --upgrade soul-protocol==0.3.4
v0.3.3 — headless standard, primitives, safety net, visibility completion
The "headless standard" release. Soul Protocol is now positioned as a language-agnostic standard with a Python reference implementation, plus the rest of the #97 visibility work and a safety net for destructive CLI commands.
The 0.3.2 number is intentionally skipped — its scope rolled into 0.3.3 alongside the rest of the work that landed in the same session.
Headlines
docs/SPEC.md— language-agnostic contract for any third-party Soul Protocol implementation in Rust, Go, TypeScript, or a custom Python runtime.- 5 journal/retrieval primitives —
Journal.appendreturns the committed entry,Journal.query(action_prefix=...), typedDataRef,RetrievalRequest.point_in_time, asyncSourceAdapter.aquery+RetrievalRouter.adispatch. - Spec-level retrieval vocabulary —
Credential,CredentialBroker,SourceAdapter,AsyncSourceAdapter, and theRetrievalErrorhierarchy moved intospec/retrieval.py. ConcreteRetrievalRouter/InMemoryCredentialBrokerremoved from this package and now ship in pocketpaw. - Backup-before-cleanup safety net —
soul cleanupandsoul forgetare dry-run by default and require--applyto execute. Before any destructive save, a side-by-side.soul.bakis written. Closes #148. - System prompt safety guardrails —
Soul.to_system_prompt()appends a default safety section so the agent doesn't surface core memory, bond details, or evolution history when asked. Soul.public_profile()— safe-to-expose subset of identity for registries and peer discovery.- The visibility tier work shipped in PR #114 plus the two pieces above close the remaining surface of #97.
Tests
2371 passed, 4 warnings
Migration
If you import from soul_protocol.engine.retrieval, switch to soul_protocol.spec.retrieval. If you depend on the concrete RetrievalRouter / InMemoryCredentialBroker, those are now in pocketpaw.retrieval (pocketpaw v0.4.17+). See CHANGELOG.md for the full migration table.
Closes
v0.3.1 — Org layer, decision traces, Zero-Copy infra
[0.3.1] -- 2026-04-14
Added
- Org-level event journal — append-only event log with SQLite WAL backend, atomic
seqallocation, and opportunistic hash-chain for tamper evidence.EventEntry,Actor, andDataRefspec types land insoul_protocol.spec. Journal entries flow through the org layer for audit and replay. (#165, #172) - Decision traces — three new event types (
agent.proposed,human.corrected,decision.graduated) withcausation_idchaining so a correction links back to the proposal that triggered it. Helpers for building a trace, querying by chain, and clustering recurring correction patterns. This is the core moat — the graduation from "the agent guessed" to "the human decided, and here's the receipt." (#168) - Retrieval router + credential broker — Zero-Copy data federation for the org layer. Router resolves a
DataRefagainst registered adapters, broker scopes credentials per source and fails closed with an audit event on any denial. No data is copied into the org boundary; only the receipt is. (#169) soul orgCLI —init,status, anddestroycommands to bootstrap an org, inspect its current state (root agent, journal head, adapter registry), and tear it down cleanly.destroyarchives the org to~/.soul-archives/before wiping so nothing is ever truly lost on an accident. (#167, #170)- Root Agent — the governance-only agent that sits above the org. Three-layer undeletability (storage-level guard on the file, protocol-level guard in the journal, CLI-level refusal to delete) makes it structurally impossible to remove by accident. Can propose, cannot execute — by design. (#170)
- Default archives directory at
~/.soul-archives/as a sibling of the org directory sosoul org destroyarchives survive a wipe of the org dir itself. MemoryEntry.scope+match_scopehelper — scope tags on memories with a matcher that uses the spec-level grammar (org:*,agent:<id>,session:<id>, etc.). Recalls can now filter by scope without reaching into tier internals. (#162)RetrievalTracereceipt — every recall now produces a trace with the query, candidate set, rerank decisions, and final selection. Exposed at runtime viaSoul.last_retrievalso callers can introspect why a given memory surfaced. (#161)- Bundled role archetype templates — Arrow, Flash, Cyborg, and Analyst templates ship with the package.
load_template()loads them by name, and the newsoul templateCLI lists and instantiates them. (#163) SOUL_USERS_DIRenv var + improved--users-dirdefault — user souls now nest under--data-dirby default (sosoul org init --data-dir /tmp/fookeeps founder souls in/tmp/foo/users/instead of the real~/.soul/users/). TheSOUL_USERS_DIRenv var overrides without a flag, and an explicit--users-diroverrides both. The pre-v0.3.1 behavior of always writing to~/.soul/users/(regardless of--data-dir) silently polluted home directories during CI runs and isolated demos.- Framework-agnostic Org Journal Spec at
docs/org-journal-spec.mdso other implementations can target the same wire format without reading the Python source. (#164) - Manual testing guide at
docs/manual-testing.mdfor org-layer flows that are awkward to cover in unit tests. (#164)
Changed
- Architecture doc trimmed — org-layer detail moved to the dedicated spec so
docs/architecture.mdstays focused on the soul runtime. (#164) - Doc examples neutralized — replaced PocketPaw-specific wording so the docs land cleanly for anyone using the protocol from their own stack. (#171)
Fixed
- Bare
pip install soul-protocolnow produces a workingsoulCLI. The CLI's required dependencies (click,rich,pyyaml,cryptography) have moved from the[engine]extra into basedependencies, sosoul --helpno longer raisesImportErroron a minimal install. The[engine]extra is kept as an empty backwards-compat alias so existingpip install soul-protocol[engine]pins continue to resolve. (#173, fixes #157) smart_recallnow populatesSoul.last_retrievalwith aRetrievalTracereceipt. The original #161 instrumentation coveredrecall()only becausesmart_recallwas not on dev at the time; this closes the gap. The trace carriessource="soul.smart"and metadata flags that record whether rerank ran.match_scopeis now bidirectional containment: a caller with scopeorg:sales:leadsmatches a memory taggedorg:sales:*(and vice versa). The previous asymmetric behaviour made bundled archetypes' core memories invisible to agents installed from them. The fix makes the glob-styledefault_scopein Arrow, Flash, Cyborg, and Analyst actually functional out of the box. The old one-way variant is preserved asmatch_scope_strict.
v0.3.0 — Dream Cycle, Smart Recall, Significance Short-Circuit
Three new features shipped in this release, all off-by-default or backward compatible.
Highlights
Dream cycle
Soul.dream() is the offline counterpart to observe(). Reviews accumulated episodes in batch to detect topic clusters, extract recurring procedures, detect behavioral trends, consolidate the knowledge graph, and synthesize cross-tier insights (episodes → procedural memories, behavioral patterns → OCEAN evolution proposals). No LLM required — all heuristic.
soul dream .soul/ --dry-run # Preview without mutating
soul dream .soul/ # Real cycle
soul dream .soul/ --since 2026-04-01 --jsonThe new --dry-run flag runs the full analysis pipeline and reports what would change, but skips every destructive mutation. Useful for checking what a cycle would do before committing.
Smart recall
Soul.smart_recall() uses the CognitiveEngine to rerank a heuristic candidate pool for better context-aware relevance. Opt-in by design — disabled by default to protect high-frequency callers from unbounded token cost.
soul = await Soul.awaken("aria.soul")
# Opt in per-soul
soul._memory.settings.smart_recall_enabled = True
memories = await soul.smart_recall("what did we discuss about auth?")
# Or override per-call
memories = await soul.smart_recall("auth", enabled=True)Security hardening: angle brackets stripped from memory content, response-marker strings redacted, memories isolated inside a BEGIN/END MEMORIES fence in the prompt. Adversarial memories can't hijack the rerank. 30-second hard timeout on the LLM call with clean fallback to heuristic order on timeout, parse error, or engine failure.
Significance short-circuit
observe() now skips entity extraction (step 5) and self-model update (step 6) when an interaction scores below the significance threshold AND fact extraction finds nothing. Saves roughly two LLM calls per trivial interaction.
Gated by MemorySettings.skip_deep_processing_on_low_significance (default True) with an escape hatch (False) for callers that need guaranteed extraction. The gate re-checks significant after step 4b fact-based promotion, so meaningful short messages still trigger the full pipeline.
soul remember --type
The CLI now accepts --type/-t episodic|semantic|procedural. Fixes a long-standing gap where the runtime Soul.remember() supported tier selection but the CLI always defaulted to semantic.
soul remember aria.soul "Shipped v0.3 today" --type episodic --importance 8
soul remember aria.soul "User prefers Python" --type semantic
soul remember aria.soul "To deploy: make deploy" --type proceduralBackward compatibility
- All new features are off-by-default or preserve existing behavior
MemorySettingsgainssmart_recall_enabled(defaultFalse) andskip_deep_processing_on_low_significance(defaultTrue) — existing souls see no change- Existing CLI commands behave identically; new flags are optional
Tests
- 2091 tests passing (up from 2010)
- New files:
test_dream.py(52 tests),test_rerank.py(20 tests) - New classes:
TestDreamerDryRun,TestSignificanceShortCircuit
Install
pip install soul-protocol==0.3.0
# or
uv add soul-protocol==0.3.0Full changelog
See CHANGELOG.md for the complete release notes.
v0.2.9 — Skills decay, progressive recall, archival memory, auto-consolidation
Audited soul-protocol docs against the actual implementation and found 5 features that were partially built but never wired into the runtime pipeline. This release connects all of them. 2010 tests passing.
What's new
Significance-weighted skills with decay
- XP grants now range 5-30 based on interaction significance (was flat +10)
- Dormant skills lose 1 XP per day inactive, floor at 0, never reduces level
decay_all()runs at the start of everyobserve()call
Progressive recall
recall(progressive=True)returns primary entries with full content + overflow entries with L0 abstracts- Overflow entries use
model_copy()to avoid mutating in-store objects is_summarizedruntime marker distinguishes full vs abstract entries
Archival memory
archive_old_memories()compresses episodic entries older than 48h intoConversationArchive- Archived entries filtered from recall — no stale results
- Archives persist through export/awaken with full provenance (memory_refs)
Auto-consolidation
observe()auto-triggers archive + reflect everyconsolidation_intervalinteractions (default 20)- Without a CognitiveEngine, only archival runs (no reflection)
interaction_countpersisted in SoulConfig across sessions- Set
consolidation_interval=0to disable
Eternal storage wiring
Soul.archive(tiers=["ipfs"])— archive to eternal storageEternalStorageManager.with_mocks()— convenience factory with mock IPFS + Arweaveeternal=param onSoul.birth()andSoul.awaken()soul.export(path, archive=True)— auto-archive after export
Docs
- WHITEPAPER updated — skills/XP, archival memory, Conway hierarchy moved from "Not working yet" to "Working"
- Memory architecture docs — 4 new sections (archival, auto-consolidation, progressive recall, skill decay)
- Getting started — "What's new in v0.2.9" section added
- All version refs and test badges updated (2010 tests, 37 CLI commands, 23 MCP tools)
Full changelog: v0.2.8...v0.2.9
v0.2.8 — Health CLI, LLM-friendly recall, evolution persistence fix
What's new
Soul maintenance commands
soul health— audit memory tiers, duplicates, orphan nodes, bond sanitysoul cleanup— remove dupes, stale evals, orphans (--dry-run, --auto)soul repair— reset energy/bond, rebuild graph, clear evals/skills
LLM-friendly recall
soul recall --full— complete memory content, no truncationsoul recall --json— machine-readable JSON output for AI agents
8 new MCP tools (27 total)
- Psychology pipeline: soul_skills, soul_evaluate, soul_learn, soul_evolve, soul_bond
- Maintenance: soul_forget, soul_edit_core, soul_health, soul_cleanup
Always-on biorhythms (breaking change)
- Default biorhythms now always-on (energy/social drain = 0, tired threshold = 0)
- Companion souls opt-in to drain via explicit config
- New docs section explaining when to use drain vs always-on
Bug fixes
- Evolution pending mutations now persist across save/reload cycles
- ollama extra now correctly includes httpx dependency
Docs
- All counts synced (1959 tests, 37 CLI commands, 27 MCP tools)
- Biorhythm defaults corrected across all docs
- Added archive/recover/eternal-status to CLI reference
- SKILL.md .soul format and MCP mapping table corrected
Full changelog: v0.2.7...v0.2.8
v0.2.7 — Psychology Pipeline Audit
An audit of the live PocketPaw soul revealed that 5 out of 10 claimed psychology features were broken or dead code. This release fixes all of them.
Fixed
- Bond system — context_for() now passes actual bond strength to memory recall (was hardcoded to 100.0)
- Evolution pipeline — observe() now calls evaluate() to build history, so evolution triggers actually fire
- Entity extraction — new topic patterns capture concepts from natural speech
- Heuristic evaluator — recalibrated scoring so solid conversations score ~0.65-0.80 (was ~0.33)
Added
- Skills persistence — learned skills survive export/awaken cycles
- Evaluation history persistence — evaluation streaks accumulate across sessions
- 18 real-world e2e tests — 8 scenarios simulating realistic human conversations
Live validation (8-turn session on PocketPaw soul)
- 20 skills learned (Python, Pydantic, Docker, Redis...)
- 8 evaluations scored (avg 0.74)
- Evolution triggered for the first time ever (streak=8, 4 mutations proposed)
- Knowledge graph: 108 → 118 nodes
- All state persists through export/awaken
1903 tests passing, 0 regressions.
Full Changelog: v0.2.6...v0.2.7
Soul Protocol v0.2.6
Soul Protocol v0.2.6
1,885 tests passing | Python 3.11+ | MIT License
Features
- MCP LCM Context Tools — 5 new tools expose Lossless Context Management through the MCP server:
soul_context_ingest,soul_context_assemble,soul_context_grep,soul_context_expand,soul_context_describe. Per-soul in-memory SQLite stores with CognitiveEngine auto-wired to compactors for LLM-powered summarization (#138) - CLI Runtime Parity — 13 new commands bring the CLI to full feature parity with the Python API:
observe,reflect,feel,prompt,forget,edit-core,evolve,evaluate,learn,skills,bond,events,context. Total: 34 commands (#138) - Soul Directory Auto-detect — MCP server now finds
.soul/in the working directory or~/.soul/when noSOUL_DIR/SOUL_PATHenv var is set. UsesPath.cwd()so it works for all install modes (editable, wheel, uvx). Logs empty directory fallthrough (#136)
Bug Fixes
- Dedup containment coefficient — enriched facts (where a short fact is a subset of a longer version) now correctly land in MERGE range instead of CREATE. Containment coefficient (
intersection / min-set * 0.75) used as floor for Jaccard, withmin_size >= 3guard against spurious short-text matches (#135) - CI dependency resolution —
dspyandlitellmextras emptied to preventuv syncfrom failing on unresolvable transitive dependencies. Both can still be installed manually (#136) - MCP test isolation — autouse fixture now monkeypatches CWD and
Path.home()to prevent auto-detect from loading real souls during tests (#136)
Docs
- Guides refreshed for v0.2.5 features — getting-started (new extras,
engine="auto"), cognitive-engine (adapters, MCP sampling), integrations (A2A bridge, format importers), memory-architecture (visibility tiers, contradiction pipeline, LCM, real embeddings) (#137)
Install
```bash
pip install soul-protocol==0.2.6
With extras
pip install "soul-protocol[anthropic]" # Anthropic Claude engine
pip install "soul-protocol[openai]" # OpenAI engine
pip install "soul-protocol[mcp]" # MCP server + sampling
pip install "soul-protocol[embeddings-st]" # SentenceTransformer embeddings
pip install "soul-protocol[all]" # Everything
```
Full Changelog
https://github.com/qbtrix/soul-protocol/blob/main/CHANGELOG.md
Soul Protocol v0.2.5
Soul Protocol v0.2.5
1,883 tests passing | Python 3.11+ | MIT License
Features
- Cognitive Adapters — drop-in LLM engines for any provider:
AnthropicEngine,OpenAIEngine,OllamaEngine,LiteLLMEngine,CallableEngine, plusengine_from_env()auto-detection andengine="auto"shortcut onSoul.birth()/Soul.awaken()(#122, #131) - MCP Sampling Engine —
MCPSamplingEngineroutes cognitive tasks to the host LLM via MCPctx.sample(). Zero extra API key — works out of the box in Claude Code, Claude Desktop, and any MCP-compatible host (#122, #131) - Real Semantic Embeddings — three new providers:
SentenceTransformerEmbedder,OpenAIEmbedder,OllamaEmbedder. Drop into the memory pipeline for vector-based recall (#111) - Lossless Context Management (LCM) —
soul_protocol.runtime.contextpackage with SQLite-backed conversation store, three-level compaction (Summary → Bullets → Truncate), and relevance-weighted retrieval. Keeps conversations coherent at 100k+ tokens. Zero new dependencies (#112, #128) - Memory Visibility Tiers —
MemoryVisibilityenum (PUBLIC,BONDED,PRIVATE) on everyMemoryEntry. Recall is automatically filtered by requester identity and bond strength (#114, #125) - Soul Templates & SoulFactory — define archetypes once, stamp out multiple souls. Great for simulations, multi-agent pipelines, and testing (#114, #125)
- Multi-Participant Interactions —
Interactiongeneralizes to N participants with full backward compat (user_input/agent_outputstill work).Identity.bondsreplaces deprecatedbonded_towithlist[BondTarget]and auto-migration (#113) - A2A Agent Card Bridge — bidirectional conversion between
.soulfiles and Google A2AAgentCardformat. CLI:soul export-a2a/soul import-a2a(#116, #129) - Format Importers — import characters from other platforms into
.soul:SoulSpecImporter(SOUL.md / soul.json) andTavernAIImporter(Character Card V2 — JSON and PNG with embedded tEXt chunk, no Pillow needed) (#117, #130) - Graph Traversal — BFS/DFS traversal, shortest path, subgraph extraction, centrality scoring, and
progressive_context()for token-budget-aware context injection (#115, #127) - Learning Events —
LearningEventspec model wired intoSoul.learn()for structured skill acquisition tracking (#115, #127)
Bug Fixes
- Contradiction pipeline gap —
observe()now runs a raw-text contradiction scan against the semantic store on every memory write. Location/employer changes (moved to,joined,works at) are correctly detected and superseded (#123, #133) - Entity extractor sparse graphs — added third-person relationship patterns (
managed_by,reports_to,leads,works_at, etc.) for richer knowledge graphs (#123, #133) - Verb-fact contradiction patterns —
_VERB_FACT_PATTERNScovers lifestyle fact changes that previously slipped under the Jaccard similarity threshold (#123, #133) - Duplicate
progressive_context()method — renamed conflicting string-format version toformat_context()after #115 + #122 merge collision (#132) - Broken
spec/learning.pyimport — added missing module after #114 merged before #115 (#126) - Dedup short-token false positives — tokenizer now preserves 2-char tokens (
Go,JS,AI,ML) instead of collapsing them (#109) - Test collection errors — guarded optional-dep imports (
numpy,fastmcp) withpytest.importorskip(#134)
CI/CD
- Auto-publish to PyPI —
publish.ymlworkflow triggers on GitHub release creation (#106)
Docs & Community
- soul-protocol skill — published to skills.sh for discoverability (#72)
- Updated README with new extras table,
engine="auto"quickstart, and test count
Install
pip install soul-protocol==0.2.5
# LLM Engines
pip install "soul-protocol[anthropic]" # Anthropic Claude
pip install "soul-protocol[openai]" # OpenAI / compatible endpoints
pip install "soul-protocol[ollama]" # Ollama (local models)
pip install "soul-protocol[litellm]" # LiteLLM (100+ providers)
pip install "soul-protocol[llm]" # All LLM engines
# Embeddings
pip install "soul-protocol[embeddings-st]" # SentenceTransformer (local)
pip install "soul-protocol[embeddings-openai]" # OpenAI embeddings
pip install "soul-protocol[embeddings-ollama]" # Ollama embeddings
# Infrastructure
pip install "soul-protocol[mcp]" # MCP server + sampling
pip install "soul-protocol[graph]" # Knowledge graph (NetworkX)
pip install "soul-protocol[all]" # EverythingFull Changelog
https://github.com/qbtrix/soul-protocol/blob/main/CHANGELOG.md