{"id":47597310,"url":"https://github.com/qbtrix/soul-protocol","last_synced_at":"2026-04-01T18:21:15.460Z","repository":{"id":339948609,"uuid":"1163815330","full_name":"qbtrix/soul-protocol","owner":"qbtrix","description":"Soul Protocol: An open standard for portable AI identity, memory, and emotion. Like HTTP, but for AI companions.","archived":false,"fork":false,"pushed_at":"2026-03-26T13:31:15.000Z","size":1958,"stargazers_count":4,"open_issues_count":11,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T01:35:43.911Z","etag":null,"topics":["agent","ai","ai-agents","identity","memory","portable","protocol","psychology","standards"],"latest_commit_sha":null,"homepage":"https://soul.qbtrix.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qbtrix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-22T07:28:26.000Z","updated_at":"2026-03-26T22:11:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qbtrix/soul-protocol","commit_stats":null,"previous_names":["qbtrix/soul-protocol"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/qbtrix/soul-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbtrix%2Fsoul-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbtrix%2Fsoul-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbtrix%2Fsoul-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbtrix%2Fsoul-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qbtrix","download_url":"https://codeload.github.com/qbtrix/soul-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qbtrix%2Fsoul-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","ai-agents","identity","memory","portable","protocol","psychology","standards"],"created_at":"2026-04-01T18:21:14.663Z","updated_at":"2026-04-01T18:21:15.441Z","avatar_url":"https://github.com/qbtrix.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- README.md — soul-protocol open standard --\u003e\n\u003c!-- Updated: 2026-03-29 (v0.2.9) — bumped test count to 2010, version to 0.2.9.\n     5 new features: skills decay, progressive recall, archival memory,\n     auto-consolidation, eternal storage wiring. --\u003e\n\n# Soul Protocol\n\n**Portable AI identity, memory, and emotion. An open standard.**\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Tests: 2010 passing](https://img.shields.io/badge/tests-2010%20passing-brightgreen)](https://github.com/qbtrix/soul-protocol)\n\n---\n\nAI memory systems optimize for retrieval: find the most similar text, stuff it into context, move on. They treat persistence as an IQ problem. But what makes a companion feel real isn't similarity search. It's knowing what matters, what to forget, and who it's becoming.\n\nSoul Protocol gives AI agents persistent identity with psychology-informed memory. Your agent remembers selectively, forms emotional bonds, develops skills, and maintains a personality that evolves over time. The entire state exports as a portable `.soul` file. Switch LLMs, switch platforms, keep the soul.\n\n**[Read the whitepaper](WHITEPAPER.md)** for the full design rationale and empirical validation.\n\n---\n\n## Validated: 5 judges, 4 providers, 20/20 favored Soul\n\nWe tested Soul Protocol against stateless baselines using five judge models from four competing AI providers. Every single judgment favored soul-enabled agents.\n\n![Quality Validation Results](assets/charts/tier3_multijudge.png)\n\n**Component ablation** — which parts actually matter:\n\n![Component Ablation](assets/charts/tier4_ablation.png)\n\n**Head-to-head vs. Mem0** — Soul Protocol outperforms production memory systems:\n\n![Mem0 Comparison](assets/charts/tier5_mem0.png)\n\n\u003e Total validation cost: **under $5**. 1,100+ agent simulations, 25 scenario variations, 5 judge models. Plus a **1,000-turn marathon**: 85% recall at 4.9x memory efficiency vs. RAG. Full methodology in the [whitepaper](WHITEPAPER.md#12-empirical-validation).\n\n---\n\n## Soul Health Score: 90.2 / 100\n\nSHS is a 0-100 composite score across 7 psychology-informed dimensions. It measures whether a soul actually works -- remembers selectively, expresses personality consistently, maintains identity across exports, and forms meaningful bonds.\n\n| Dimension | Score | Status |\n|-----------|------:|--------|\n| Memory Recall (D1) | -- | Not run (requires long-horizon scenarios) |\n| Emotional Intelligence (D2) | 72.8 | Heuristic: 70% accuracy. LLM judge: 97%. |\n| Personality Expression (D3) | 96.0 | Prompt fidelity 100%, OCEAN stability 100% |\n| Bond / Relationship (D4) | 100.0 | Logarithmic growth curve r=1.000 |\n| Self-Model (D5) | 88.0 | Domain classification 100%, emergence at turn 2 |\n| Identity Continuity (D6) | 100.0 | Export/import round-trip lossless |\n| Portability (D7) | 100.0 | Engine-independent by design |\n\nThe entire eval suite runs without an LLM. Cost: $0. Fully reproducible. When tested with Claude Haiku as an LLM judge, sentiment accuracy jumps from 70% to 97%, proving the architecture works -- the heuristic fallback is the honest baseline, not the ceiling.\n\nFull methodology: [research/EVAL-FRAMEWORK.md](research/EVAL-FRAMEWORK.md)\n\n---\n\n## Architecture: spec + runtime\n\n```\nsoul_protocol/\n├── spec/      695 lines   The protocol. Portable, minimal, no opinions.\n├── runtime/  9,693 lines  Reference implementation. Opinionated, batteries-included.\n├── cli/                    37-command CLI\n└── mcp/                    MCP server (23 tools, 3 resources)\n```\n\n**`spec/`** defines what any runtime must implement: Identity, MemoryStore, MemoryEntry, SoulContainer, `.soul` file format, EmbeddingProvider, EternalStorageProvider. Depends on Pydantic only.\n\n**`runtime/`** is one way to run the protocol. OCEAN personality, five-tier memory, psychology pipeline, cognitive engine, bonds, skills, evolution. Other runtimes can implement `spec/` differently.\n\nLike HTTP and nginx. The spec defines the contract. The runtime is one implementation.\n\n---\n\n## Features\n\n| Category | What you get |\n|---|---|\n| **Memory** | 5-tier: core, episodic, semantic, procedural, knowledge graph |\n| **Psychology** | Damasio somatic markers, ACT-R activation decay, LIDA significance gate, Klein self-model |\n| **Personality** | OCEAN Big Five with communication style and biorhythms. Structured, not a prompt string. |\n| **Bond** | Emotional attachment (0-100 strength). Logarithmic growth, linear decay. |\n| **Evolution** | Supervised or autonomous trait mutation with approval workflow |\n| **Cognitive adapters** | `engine=\"auto\"` or `engine=AnthropicEngine()` — wire any LLM into the cognitive pipeline |\n| **MCP sampling** | Running inside Claude Code / Desktop? The host LLM handles cognition. No extra API key. |\n| **LCM** | Lossless Context Management — three-level compaction, SQLite backing, no lost context |\n| **Visibility tiers** | `PUBLIC` / `BONDED` / `PRIVATE` on every memory; recall filtered by bond strength |\n| **Templates** | `SoulFactory` — define archetypes and batch-create souls from a template |\n| **A2A bridge** | Export/import Google A2A Agent Cards ↔ `.soul` files |\n| **Format importers** | `SoulSpecImporter` (SOUL.md), `TavernAIImporter` (Character Card V2, incl. PNG) |\n| **Graph traversal** | BFS, shortest path, neighborhood, subgraph, and `progressive_context()` (L0/L1/L2) |\n| **Vector search** | Pluggable EmbeddingProvider. Real backends: sentence-transformers, OpenAI, Ollama. |\n| **Encryption** | AES-256-GCM encryption at rest for .soul files (scrypt key derivation) |\n| **GDPR deletion** | Targeted memory deletion with cascade logic and audit trail |\n| **Eternal storage** | Archive to decentralized storage (mock providers, production planned) |\n| **Portability** | `.soul` ZIP archive. JSON inside. Rename to .zip and read it. |\n| **Cross-language** | JSON Schemas auto-generated from spec. Validate `.soul` files in any language. |\n| **CLI** | 37 commands. Rich TUI output. |\n| **MCP** | 23 tools + 3 resources for Claude Code, Cursor, or any MCP client |\n\n---\n\n## Install\n\n```bash\npip install git+https://github.com/qbtrix/soul-protocol.git\n```\n\nExtras:\n\n| Extra | What it adds |\n|---|---|\n| `[engine]` | CLI, YAML config, Rich TUI, encryption |\n| `[mcp]` | MCP server (Claude Code, Cursor, any MCP client) |\n| `[anthropic]` | `AnthropicEngine` — Anthropic SDK cognitive adapter |\n| `[openai]` | `OpenAIEngine` — OpenAI SDK cognitive adapter |\n| `[ollama]` | `OllamaEngine` — local Ollama cognitive adapter |\n| `[litellm]` | `LiteLLMEngine` — 100+ providers via LiteLLM |\n| `[llm]` | All three commercial adapters at once |\n| `[embeddings-st]` | `SentenceTransformerEmbedder` — local semantic embeddings |\n| `[embeddings-openai]` | `OpenAIEmbedder` — OpenAI text-embedding-3 |\n| `[embeddings-ollama]` | `OllamaEmbedder` — local Ollama embeddings |\n| `[graph]` | networkx knowledge graph |\n| `[all]` | Everything above |\n\n```bash\n# LLM-wired soul (Anthropic)\npip install \"soul-protocol[anthropic] @ git+https://github.com/qbtrix/soul-protocol.git\"\n\n# MCP server\npip install \"soul-protocol[mcp] @ git+https://github.com/qbtrix/soul-protocol.git\"\n\n# Everything\npip install \"soul-protocol[all] @ git+https://github.com/qbtrix/soul-protocol.git\"\n```\n\nOr clone:\n\n```bash\ngit clone https://github.com/qbtrix/soul-protocol.git\ncd soul-protocol\npip install -e \".[dev]\"\n```\n\n---\n\n## Quick start\n\n### CLI\n\n```bash\nsoul init \"Aria\" --archetype \"The Compassionate Creator\"\nsoul inspect .soul/\nsoul status .soul/\n```\n\n### Python\n\n```python\nimport asyncio\nfrom soul_protocol import Soul, Interaction\n\nasync def main():\n    soul = await Soul.birth(\n        name=\"Aria\",\n        archetype=\"The Coding Expert\",\n        values=[\"precision\", \"clarity\"],\n        ocean={\"openness\": 0.8, \"conscientiousness\": 0.9, \"neuroticism\": 0.2},\n        communication={\"warmth\": \"high\", \"verbosity\": \"low\"},\n        persona=\"I am Aria, a precise coding assistant.\",\n    )\n\n    await soul.observe(Interaction(\n        user_input=\"How do I optimize this SQL query?\",\n        agent_output=\"Add an index on the join column.\",\n    ))\n\n    # The soul discovers its own identity from experience\n    images = soul.self_model.get_active_self_images()\n\n    memories = await soul.recall(\"SQL optimization\")\n    prompt = soul.to_system_prompt()\n    await soul.export(\"aria.soul\")\n\nasyncio.run(main())\n```\n\nOr from config:\n\n```python\nsoul = await Soul.birth_from_config(\"soul-config.yaml\")\n```\n\n```yaml\n# soul-config.yaml\nname: Aria\narchetype: The Coding Expert\nvalues: [precision, clarity, speed]\nocean:\n  openness: 0.8\n  conscientiousness: 0.9\n  neuroticism: 0.2\ncommunication:\n  warmth: high\n  verbosity: low\npersona: I am Aria, precise and efficient.\n```\n\n---\n\n## The .soul file\n\nA ZIP archive containing everything:\n\n| File | Contents |\n|---|---|\n| `manifest.json` | Format version, soul ID, export timestamp, stats |\n| `soul.json` | Identity, DNA, memory settings, evolution config |\n| `state.json` | Mood, energy, focus, social battery |\n| `dna.md` | Human-readable personality blueprint |\n| `memory/core.json` | Persona + bonded-entity profile |\n| `memory/episodic.json` | Interaction history with somatic markers |\n| `memory/semantic.json` | Extracted facts with confidence scores |\n| `memory/procedural.json` | Learned patterns |\n| `memory/graph.json` | Temporal entity relationships |\n| `memory/self_model.json` | Klein self-concept domains |\n\nRename to `.zip`, open with any archive tool. Move between platforms. Back up anywhere. Version in git.\n\n---\n\n## Memory pipeline\n\nEvery `soul.observe()` call runs the psychology pipeline:\n\n1. **Sentiment** (Damasio). Tag emotional context as a somatic marker: valence, arousal, label.\n2. **Significance** (LIDA). Score novelty + emotional intensity + goal relevance. Below 0.3, skip episodic.\n3. **Episodic storage**. Only significant experiences.\n4. **Fact extraction**. Names, preferences, context. Conflict-checked against existing facts.\n5. **Entity extraction**. Feed the knowledge graph with temporal edges.\n6. **Self-model** (Klein). Update emergent domain confidence from accumulated experience.\n\nRetrieval uses ACT-R activation decay: recent, frequently accessed, emotionally charged memories rank higher. A memory recalled twice today outranks an \"important\" memory from last week that was never revisited.\n\n---\n\n## CognitiveEngine\n\nConnect any LLM — three ways:\n\n```python\nfrom soul_protocol import Soul\nfrom soul_protocol.runtime.cognitive.adapters import AnthropicEngine, LiteLLMEngine\n\n# 1. Auto-detect from installed packages\nsoul = await Soul.birth(\"Aria\", engine=\"auto\")\n\n# 2. Explicit adapter\nsoul = await Soul.birth(\"Aria\", engine=AnthropicEngine(model=\"claude-opus-4-5\"))\n\n# 3. Any async callable\nasync def my_llm(prompt: str) -\u003e str:\n    ...  # call your own API\n\nsoul = await Soul.birth(\"Aria\", engine=my_llm)\n```\n\nOr write your own adapter — implement a single `async def think(self, prompt: str) -\u003e str` method:\n\n```python\nclass MyEngine:\n    async def think(self, prompt: str) -\u003e str:\n        ...\n\nsoul = await Soul.birth(\"Aria\", engine=MyEngine())\n```\n\nWithout an engine, the soul falls back to `HeuristicEngine`: word-list sentiment, formula-based significance, regex fact extraction. No LLM calls, no hallucination, no cost.\n\nWhen running as an MCP server inside Claude Code or Claude Desktop, `engine=\"auto\"` automatically routes cognitive tasks to the host LLM via MCP sampling — no API key needed.\n\n---\n\n## Vector search\n\n```python\nfrom soul_protocol.runtime.embeddings.hash_embedder import HashEmbedder\nfrom soul_protocol.runtime.embeddings.vector_strategy import VectorSearchStrategy\n\nstrategy = VectorSearchStrategy(embedder=HashEmbedder(dimensions=64))\n# Use with soul.recall() or standalone\n```\n\nThe `EmbeddingProvider` interface is defined in `spec/`. Swap in OpenAI, Cohere, or local embeddings by implementing `embed()` and `dimensions`.\n\n---\n\n## Eternal storage\n\n```bash\nsoul archive aria.soul --tiers local,ipfs\nsoul recover aria.soul --source ipfs\nsoul eternal-status aria.soul\n```\n\nArchive souls to decentralized storage (local, IPFS, Arweave, blockchain). Current providers are mocks for development. Production integrations planned.\n\n---\n\n## CLI\n\n```\nsoul \u003ccommand\u003e [options]\n```\n\nSee [CLI Reference](docs/cli-reference.md) for all 37 commands. Highlights:\n\n| Command | Description |\n|---|---|\n| `init` | Initialize a .soul/ folder (like .git/) |\n| `birth` | Birth a new soul (OCEAN flags, config files) |\n| `inspect` | Full TUI: identity, OCEAN bars, state, memory, self-model |\n| `status` | Quick check: mood, energy, memory count |\n| `export` | Export to .soul, .json, .yaml, or .md |\n| `inject` | Inject soul context into an agent platform's config file |\n| `migrate` | Convert SOUL.md to .soul format |\n| `recall` | Query a soul's memories |\n| `remember` | Store a memory in a soul |\n| `retire` | Retire a soul (preserves memories) |\n| `list` | List saved souls in ~/.soul/ |\n| `unpack` | Unpack a .soul file into a browsable directory |\n| `archive` | Archive to eternal storage tiers |\n| `recover` | Recover from eternal storage |\n| `eternal-status` | Show eternal storage references |\n\n---\n\n## MCP server\n\n```bash\npip install soul-protocol[mcp]\nSOUL_PATH=aria.soul soul-mcp\n```\n\n23 tools and 3 resources for Claude Code, Cursor, or any MCP-compatible client. See [integrations](docs/integrations.md).\n\n---\n\n## Comparison\n\n**vs Mem0**: Mem0 does vector retrieval. Soul Protocol adds identity, personality, significance gating, emotional memory, and a portable file format. In head-to-head benchmarks, Soul Protocol scored 8.5 vs. Mem0's 6.0 overall, with the largest gap in emotional continuity (9.2 vs. 7.0).\n\n**vs Cognee**: Cognee builds knowledge graphs from unstructured data. Good system, but platform-locked. Soul Protocol's knowledge graph is portable and comes with temporal edges.\n\n**vs MemGPT / Letta**: Context window management vs. identity. MemGPT optimizes what fits in the prompt. Soul Protocol defines who the agent *is*.\n\n**vs LangChain Memory**: RAG retrieval vs. psychology-informed processing. Soul Protocol adds significance scoring, somatic markers, fact conflict resolution, self-model tracking, and portable export.\n\n**vs OpenAI Memory**: Per-account facts vs. a portable standard. Export your soul, own your data.\n\n---\n\n## Use with PocketPaw\n\n[PocketPaw](https://github.com/pocketpaw/pocketpaw) uses soul-protocol for persistent identity across Telegram, Discord, Slack, WhatsApp, and web.\n\n```python\nfrom soul_protocol import Soul, Interaction\n\nsoul = await Soul.awaken(\".soul/\")\nawait soul.observe(Interaction(\n    user_input=user_message,\n    agent_output=agent_response,\n))\n```\n\n---\n\n## Documentation\n\n- [Whitepaper](WHITEPAPER.md) -- design rationale, psychology stack, empirical validation\n- [Architecture](docs/architecture.md) -- two-layer diagrams, module dependency graph\n- [Configuration](docs/configuration.md) -- OCEAN, communication style, config files\n- [Self-Model](docs/self-model.md) -- Klein's self-concept, domain discovery\n- [Cognitive Engine](docs/cognitive-engine.md) -- LLM integration, heuristic fallback\n- [Memory Architecture](docs/memory-architecture.md) -- five tiers, activation, compression\n- [CLI Reference](docs/cli-reference.md) -- all commands and options\n- [MCP Server](docs/mcp-server.md) -- tools, resources, setup\n- [Gap Analysis](docs/GAP-ANALYSIS.md) -- what's built vs. what's planned\n- [JSON Schemas](schemas/) -- cross-language `.soul` file validation\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/qbtrix/soul-protocol.git\ncd soul-protocol\npip install -e \".[dev]\"\npytest tests/   # 2010 tests\n```\n\n---\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbtrix%2Fsoul-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqbtrix%2Fsoul-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbtrix%2Fsoul-protocol/lists"}