soul-protocol 0.2.3__tar.gz

soul_protocol-0.2.3/.claude/CLAUDE.md

@@ -0,0 +1,16 @@
+# Soul
+
+## Soul (Persistent Memory)
+
+This project uses [Soul Protocol](https://github.com/qbtrix/soul-protocol) for persistent AI memory via MCP.
+
+**On session start:**
+1. Call `soul_recall` with the current task context to load relevant memories
+2. Call `soul_state` to check current mood and energy
+
+**During work:**
+- `soul_observe` after key decisions, completed tasks, or important conversations
+- `soul_remember` for facts that should persist across sessions
+
+**On session end:**
+- The soul auto-saves on shutdown — no manual save needed

soul_protocol-0.2.3/.continuerules

@@ -0,0 +1,16 @@
+# Soul
+
+## Soul (Persistent Memory)
+
+This project uses [Soul Protocol](https://github.com/qbtrix/soul-protocol) for persistent AI memory via MCP.
+
+**On session start:**
+1. Call `soul_recall` with the current task context to load relevant memories
+2. Call `soul_state` to check current mood and energy
+
+**During work:**
+- `soul_observe` after key decisions, completed tasks, or important conversations
+- `soul_remember` for facts that should persist across sessions
+
+**On session end:**
+- The soul auto-saves on shutdown — no manual save needed

soul_protocol-0.2.3/.github/CODEOWNERS

@@ -0,0 +1,18 @@
+# CODEOWNERS — require maintainer review for security-critical paths.
+# Added: 2026-03-05 — Initial CODEOWNERS for soul-protocol.
+
+# CI/CD workflows
+.github/ @qbtrix/core
+
+# Cryptography and signing
+src/soul_protocol/crypto/ @qbtrix/core
+
+# Dependencies
+pyproject.toml @qbtrix/core
+uv.lock @qbtrix/core
+
+# Soul file format (security-sensitive — handles identity data)
+src/soul_protocol/soul_file/ @qbtrix/core
+
+# CLI entry points
+src/soul_protocol/cli/ @qbtrix/core

soul_protocol-0.2.3/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What does this PR do?
+
+<!-- Describe the change in 2-3 sentences. Link the issue it fixes. -->
+
+Fixes #
+
+## How to test
+
+<!-- Steps to verify the change works, or paste test output. -->
+
+```
+uv run pytest tests/ -v
+```
+
+## Checklist
+
+- [ ] Tests pass locally (`uv run pytest tests/`)
+- [ ] Lint passes (`uv run ruff check . && uv run ruff format --check .`)
+- [ ] No secrets or credentials in the diff
+- [ ] PR title follows Conventional Commits (`feat:`, `fix:`, `docs:`, etc.)

soul_protocol-0.2.3/.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+# CI — lint and test on every PR and push to main.
+# Updated: 2026-03-05 — Lint errors fixed, lint job now blocks PRs.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra mcp --extra graph --extra vector
+
+      - name: Ruff check
+        run: uv run ruff check .
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra mcp --extra graph --extra vector
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

soul_protocol-0.2.3/.github/workflows/pr-quality-gate.yml

@@ -0,0 +1,306 @@
+# PR quality gate — enforces contribution standards and security checks.
+# Added: 2026-03-05 — Quality gate + security scan for soul-protocol.
+name: PR Quality Gate
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+permissions:
+  pull-requests: write
+  issues: write
+  contents: read
+
+jobs:
+  check-quality:
+    runs-on: ubuntu-latest
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      github.actor != 'renovate[bot]' &&
+      github.actor != 'github-actions[bot]'
+    steps:
+      - name: Check PR quality
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const body = pr.body || '';
+            const title = pr.title || '';
+            const base = pr.base.ref;
+            const additions = pr.additions || 0;
+            const deletions = pr.deletions || 0;
+            const changedFiles = pr.changed_files || 0;
+
+            const issues = [];
+            const warnings = [];
+            const MARKER = '<!-- pr-quality-gate -->';
+
+            // Check for conventional commit title
+            const conventionalRe = /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:\s.+/;
+            if (!conventionalRe.test(title)) {
+              issues.push('- PR title does not follow [Conventional Commits](https://www.conventionalcommits.org/) format (e.g. `feat: add recall API`, `fix(memory): handle empty tiers`).');
+            }
+
+            // Linked issue
+            const hasIssueRef = /(?:fixes|closes|resolves)\s*#\d+/i.test(body) ||
+                                /#\d+/.test(body);
+            if (!hasIssueRef) {
+              issues.push('- No linked issue found. PRs should reference an issue (`Fixes #123`).');
+            }
+
+            // Description quality
+            const strippedBody = body
+              .replace(/<!--[\s\S]*?-->/g, '')
+              .replace(/#+\s*.*/g, '')
+              .replace(/- \[ \].*/g, '')
+              .replace(/\s/g, '');
+            if (strippedBody.length < 50) {
+              issues.push('- PR description is too short. Please describe what this PR does and how to test it.');
+            }
+
+            // Testing evidence
+            const hasTestEvidence = /terminal|output|screenshot|tested|test result/i.test(body) ||
+                                    /```[\s\S]*```/.test(body);
+            if (!hasTestEvidence) {
+              issues.push('- No evidence of local testing found. Please include terminal output or screenshots.');
+            }
+
+            // Get changed file list
+            const { data: files } = await github.rest.pulls.listFiles({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: pr.number,
+              per_page: 100
+            });
+            const fileNames = files.map(f => f.filename);
+
+            // PR size gate
+            const totalLines = additions + deletions;
+            if (totalLines > 500 || changedFiles > 15) {
+              warnings.push(`- Large PR detected (${totalLines} lines across ${changedFiles} files). Consider splitting into smaller PRs.`);
+            }
+
+            // Sensitive file change alerts
+            const sensitivePatterns = [
+              { pattern: /^\.github\//, label: 'CI/CD workflows' },
+              { pattern: /^src\/soul_protocol\/crypto/, label: 'cryptography' },
+              { pattern: /^pyproject\.toml$/, label: 'project dependencies' },
+              { pattern: /^uv\.lock$/, label: 'lock file' },
+            ];
+            const touchedSensitive = [];
+            for (const { pattern, label } of sensitivePatterns) {
+              if (fileNames.some(f => pattern.test(f))) {
+                touchedSensitive.push(label);
+              }
+            }
+            if (touchedSensitive.length > 0) {
+              warnings.push(`- This PR touches sensitive files (${touchedSensitive.join(', ')}). These paths require maintainer review via CODEOWNERS.`);
+            }
+
+            // Dependency change alert
+            const depFiles = fileNames.filter(f => f === 'pyproject.toml' || f === 'uv.lock');
+            if (depFiles.length > 0) {
+              const depChanges = files.filter(f => depFiles.includes(f.filename));
+              const depDetail = depChanges.map(f => `\`${f.filename}\` (+${f.additions}/-${f.deletions})`).join(', ');
+              warnings.push(`- Dependency files changed: ${depDetail}. Reviewers: check for added/removed/changed packages.`);
+            }
+
+            // Find existing bot comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr.number,
+            });
+            const botComment = comments.find(
+              c => c.user.type === 'Bot' && c.body.includes(MARKER)
+            );
+
+            if (issues.length > 0 || warnings.length > 0) {
+              let message = `${MARKER}\n`;
+
+              if (issues.length > 0) {
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pr.number,
+                  labels: ['needs-work']
+                });
+                message += `### Issues (must fix)\n\n${issues.join('\n')}\n\n`;
+              }
+
+              if (warnings.length > 0) {
+                message += `### Heads up\n\n${warnings.join('\n')}\n\n`;
+              }
+
+              message += `Please update your PR to address these points.`;
+
+              if (botComment) {
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: botComment.id,
+                  body: message
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pr.number,
+                  body: message
+                });
+              }
+            } else {
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pr.number,
+                  name: 'needs-work'
+                });
+              } catch (e) { /* label wasn't present */ }
+
+              if (botComment) {
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: botComment.id,
+                  body: `${MARKER}\nAll quality checks passed. Thanks for the clean PR!`
+                });
+              }
+            }
+
+  security-scan:
+    runs-on: ubuntu-latest
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      github.actor != 'renovate[bot]' &&
+      github.actor != 'github-actions[bot]'
+    steps:
+      - name: Checkout PR code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get changed files
+        id: changed
+        run: |
+          FILES=$(gh pr diff ${{ github.event.pull_request.number }} --name-only 2>/dev/null || git diff --name-only origin/${{ github.event.pull_request.base.ref }}...HEAD)
+          echo "files<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$FILES" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Scan for dangerous code patterns
+        run: |
+          CHANGED_PY=$(echo "${{ steps.changed.outputs.files }}" | grep '\.py$' || true)
+          if [ -z "$CHANGED_PY" ]; then
+            echo "No Python files changed — skipping security scan."
+            exit 0
+          fi
+
+          echo "Scanning changed Python files for dangerous patterns..."
+          FOUND=0
+          REPORT=""
+
+          PATTERNS=(
+            'eval\s*\('
+            'exec\s*\('
+            'os\.system\s*\('
+            'subprocess\..*shell\s*=\s*True'
+            '__import__\s*\('
+            'pickle\.loads?\s*\('
+            'yaml\.load\s*\([^)]*$'
+            'yaml\.load\s*\([^)]*\)\s*$'
+            'marshal\.loads?\s*\('
+          )
+
+          for file in $CHANGED_PY; do
+            if [ ! -f "$file" ]; then
+              continue
+            fi
+            for pattern in "${PATTERNS[@]}"; do
+              MATCHES=$(grep -nE "$pattern" "$file" 2>/dev/null || true)
+              if [ -n "$MATCHES" ]; then
+                FOUND=1
+                REPORT+="### $file\n"
+                REPORT+='```\n'
+                REPORT+="$MATCHES\n"
+                REPORT+='```\n\n'
+              fi
+            done
+          done
+
+          if [ "$FOUND" -eq 1 ]; then
+            COMMENT_BODY=$(cat <<'COMMENT_EOF'
+          <!-- security-scan -->
+          ## Security scan: review needed
+
+          Potentially dangerous code patterns detected in changed files. A maintainer should verify these are intentional and safe.
+
+          COMMENT_EOF
+          )
+            COMMENT_BODY+=$(echo -e "$REPORT")
+
+            gh pr comment ${{ github.event.pull_request.number }} \
+              --body "$COMMENT_BODY" \
+              --edit-last 2>/dev/null || \
+            gh pr comment ${{ github.event.pull_request.number }} \
+              --body "$COMMENT_BODY"
+
+            echo "::warning::Security patterns found. Review required."
+          else
+            echo "No dangerous patterns found."
+          fi
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Check for secrets in diff
+        run: |
+          DIFF=$(git diff origin/${{ github.event.pull_request.base.ref }}...HEAD -- . ':!uv.lock' ':!*.lock' 2>/dev/null || true)
+          if [ -z "$DIFF" ]; then
+            echo "No diff to scan."
+            exit 0
+          fi
+
+          FOUND=0
+          PATTERNS=(
+            'AKIA[0-9A-Z]{16}'
+            'sk-[a-zA-Z0-9]{20,}'
+            'ghp_[a-zA-Z0-9]{36}'
+            'gho_[a-zA-Z0-9]{36}'
+            'xoxb-[0-9]+-[a-zA-Z0-9]+'
+            'xoxp-[0-9]+-[a-zA-Z0-9]+'
+            'sk_live_[a-zA-Z0-9]+'
+            '-----BEGIN (RSA |EC |DSA )?PRIVATE KEY-----'
+          )
+
+          for pattern in "${PATTERNS[@]}"; do
+            if echo "$DIFF" | grep -qE "$pattern"; then
+              FOUND=1
+              echo "::error::Potential secret detected matching pattern: $pattern"
+            fi
+          done
+
+          if [ "$FOUND" -eq 1 ]; then
+            gh pr comment ${{ github.event.pull_request.number }} \
+              --body "<!-- security-scan-secrets -->
+          ## Security scan: potential secrets detected
+
+          This PR diff appears to contain secrets or API keys. Please remove them immediately and rotate any exposed credentials.
+
+          If these are false positives (e.g., placeholder patterns in tests), a maintainer will verify." \
+              --edit-last 2>/dev/null || \
+            gh pr comment ${{ github.event.pull_request.number }} \
+              --body "<!-- security-scan-secrets -->
+          ## Security scan: potential secrets detected
+
+          This PR diff appears to contain secrets or API keys. Please remove them immediately and rotate any exposed credentials.
+
+          If these are false positives (e.g., placeholder patterns in tests), a maintainer will verify."
+            exit 1
+          fi
+
+          echo "No secrets detected in diff."
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

soul_protocol-0.2.3/.github/workflows/stale.yml

@@ -0,0 +1,37 @@
+# Stale bot — auto-close abandoned PRs and issues.
+# Added: 2026-03-05 — Initial stale config for soul-protocol.
+name: Close stale issues and PRs
+
+on:
+  schedule:
+    - cron: '0 6 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not had
+            activity in the last 30 days. It will be closed in 14 days if no further
+            activity occurs. If this is still relevant, please comment or update.
+          stale-pr-message: >
+            This PR has been automatically marked as stale because it has not had
+            activity in the last 14 days. It will be closed in 7 days if no further
+            activity occurs. If you're still working on this, please push an update
+            or leave a comment.
+          close-issue-message: Closing due to inactivity. Feel free to reopen if still relevant.
+          close-pr-message: Closing due to inactivity. If you'd like to continue, please open a new PR.
+          days-before-issue-stale: 30
+          days-before-issue-close: 14
+          days-before-pr-stale: 14
+          days-before-pr-close: 7
+          stale-issue-label: stale
+          stale-pr-label: stale
+          exempt-issue-labels: 'pinned,good first issue,roadmap'
+          exempt-pr-labels: 'pinned'

soul_protocol-0.2.3/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# UV
+uv.lock
+
+# Soul files and directories (don't commit user souls)
+*.soul
+.soul/
+
+# Simulation results
+.results/
+research/results/
+
+# Internal docs (not for public repo)
+idocs/
+.claude/worktrees/

soul_protocol-0.2.3/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "soul": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "soul-protocol[mcp]",
+        "soul-mcp"
+      ],
+      "env": {
+        "SOUL_PATH": "/private/var/folders/my/ly3fsydj59qdt_hj56rtc3dr0000gn/T/pytest-of-prakash/pytest-18/test_init_setup_preserves_exis0/.soul/testbot"
+      }
+    }
+  }
+}

soul_protocol-0.2.3/.windsurfrules

@@ -0,0 +1,16 @@
+# Soul
+
+## Soul (Persistent Memory)
+
+This project uses [Soul Protocol](https://github.com/qbtrix/soul-protocol) for persistent AI memory via MCP.
+
+**On session start:**
+1. Call `soul_recall` with the current task context to load relevant memories
+2. Call `soul_state` to check current mood and energy
+
+**During work:**
+- `soul_observe` after key decisions, completed tasks, or important conversations
+- `soul_remember` for facts that should persist across sessions
+
+**On session end:**
+- The soul auto-saves on shutdown — no manual save needed

soul_protocol-0.2.3/AGENTS.md

@@ -0,0 +1,16 @@
+# Soul
+
+## Soul (Persistent Memory)
+
+This project uses [Soul Protocol](https://github.com/qbtrix/soul-protocol) for persistent AI memory via MCP.
+
+**On session start:**
+1. Call `soul_recall` with the current task context to load relevant memories
+2. Call `soul_state` to check current mood and energy
+
+**During work:**
+- `soul_observe` after key decisions, completed tasks, or important conversations
+- `soul_remember` for facts that should persist across sessions
+
+**On session end:**
+- The soul auto-saves on shutdown — no manual save needed

soul_protocol-0.2.3/FAQ.md

@@ -0,0 +1,77 @@
+<!-- FAQ.md — Public-facing frequently asked questions for Soul Protocol.
+     Created: 2026-03-08. Adapted from idocs/HARD-QUESTIONS.md with benchmark data
+     from LAUNCH-STATUS.md and technical details from WHITEPAPER.md. -->
+
+# Frequently Asked Questions
+
+---
+
+### 1. How is this different from Mem0?
+
+Mem0 is a vector memory layer. It stores user facts and retrieves them by similarity. Soul Protocol is an identity protocol. It adds significance gating (deciding what's worth remembering), somatic markers (emotional context on every memory), ACT-R activation decay (memories strengthen or fade based on usage), and a self-model that evolves from experience. In head-to-head benchmarks on identical conversations, Soul Protocol scored 8.5 overall vs. Mem0's 6.0, with the largest gap in emotional continuity (9.2 vs. 7.0). The difference isn't retrieval quality -- it's what gets stored alongside the facts. See [docs/COMPARISON.md](docs/COMPARISON.md) for the full matrix.
+
+---
+
+### 2. How is this different from MemGPT/Letta?
+
+MemGPT manages context windows -- it pages memory in and out so an LLM can work with more information than fits in a single prompt. Soul Protocol defines who the agent *is*: personality, emotional memory, self-concept, portable identity. They solve different problems at different layers. A MemGPT system could use Soul Protocol for the identity data that gets paged into context. They're complementary, not competitive.
+
+---
+
+### 3. Why not just use vector embeddings?
+
+Vector embeddings answer "what text is similar to this query?" That's one part of memory. Human memory also uses recency and frequency (ACT-R power-law decay), emotional salience (Damasio's somatic markers), significance filtering (LIDA -- not everything deserves to be remembered), and self-relevance (memories shape who you think you are). Soul Protocol models all of these. Vector search is pluggable through the `EmbeddingProvider` interface -- the protocol ships HashEmbedder and TFIDFEmbedder, and you can swap in OpenAI, Cohere, or local embeddings. Embeddings find similar things. Psychology determines what matters. You need both.
+
+---
+
+### 4. The heuristic engine sounds like a toy.
+
+The heuristic engine (word-list sentiment, formula-based significance, regex fact extraction) is intentionally simple. It's the offline fallback for when you don't have an LLM available, when you're running tests and need deterministic results, when cost matters, or when privacy requires that no text leaves the machine. The `CognitiveEngine` protocol lets you plug in any LLM for real analysis. The architecture is: LLM when available, heuristic when not. The heuristic has a low ceiling but a high floor -- it never crashes, never costs money, never leaks data, and never hallucinates.
+
+---
+
+### 5. What about hallucinated facts?
+
+Valid concern. Current mitigations: structured JSON schemas in extraction prompts reduce hallucination, a validation layer rejects unparseable output, the heuristic fallback kicks in when LLM output can't be parsed, and fact deduplication checks token overlap against existing facts (>70% similarity = skip). The system also tracks fact conflict through `superseded_by` chains rather than silently overwriting. Planned additions include confidence scores on extracted facts, source attribution, and user correction mechanisms. The system degrades gracefully -- bad extraction results in a missed fact, not corrupted state.
+
+---
+
+### 6. How does this handle multi-user?
+
+Currently, a soul bonds to one entity (the `bonded_to` field). Multi-user is not built yet. The architecture supports it: the entity graph already tracks relationships, `Interaction.metadata` can carry user IDs, and the self-model could track per-user relationship context. The routing logic needs to be added. This is a planned feature, not a current capability.
+
+---
+
+### 7. Can I use this with my LLM? (Claude, GPT, Ollama, local)
+
+Yes. The `CognitiveEngine` protocol is a single method: `async def think(self, prompt: str) -> str`. Implement it with any LLM -- Claude, GPT, Gemini, Ollama, a local model, or anything that takes text in and returns text out. The soul handles prompt construction and response parsing internally. Without any engine at all, the `HeuristicEngine` provides deterministic processing with zero API calls. One integration point, three lines of code.
+
+---
+
+### 8. How do .soul files work exactly?
+
+A `.soul` file is a ZIP archive. Rename it to `.zip` and open it with any archive tool. Inside: `manifest.json` (version, soul ID, checksums), `soul.json` (identity, personality DNA, evolution config), `state.json` (mood, energy, focus), `dna.md` (human-readable personality blueprint), and a `memory/` directory containing `core.json`, `episodic.json`, `semantic.json`, `procedural.json`, `graph.json`, and `self_model.json`. Everything is JSON. JSON Schemas are auto-generated from the protocol models, so any language with a JSON Schema validator can read and write `.soul` files without the Python SDK.
+
+---
+
+### 9. Is there a TypeScript implementation?
+
+Not yet. The protocol spec is 624 lines of Pydantic models designed for porting. JSON Schemas are auto-generated from those models, so you can validate `.soul` files in TypeScript (or any language) today using standard JSON Schema validators. A native TypeScript SDK is on the roadmap. If you want to build one, the spec layer is intentionally small and self-contained.
+
+---
+
+### 10. Why psychology? Isn't this overengineered?
+
+The psychology isn't decoration -- it's the mechanism that makes memory selective. Without significance gating (LIDA), every interaction gets stored and you get memory bloat. Without activation decay (ACT-R), old memories never fade and retrieval degrades. Without somatic markers (Damasio), there's no emotional context and the agent can't track how a user's experience *felt*. In our component ablation, removing these components dropped emotional continuity scores from 9.3 to 7.2. The theories aren't complex to implement -- LIDA is a weighted formula, ACT-R is a power law, somatic markers are three floats. The complexity is in knowing which theories to apply, not in the code.
+
+---
+
+### 11. What about privacy/security?
+
+The `.soul` file is a local ZIP archive the user controls. No cloud required, no phone-home, no telemetry. The protocol makes zero network calls. When a `CognitiveEngine` uses a cloud LLM, interaction text goes to that provider -- but that's the consumer's choice, not the protocol's. The heuristic engine processes everything locally with zero external calls. Eternal storage (Arweave/IPFS) is opt-in and planned to support user-controlled encryption. The file format is inspectable: rename to `.zip`, read the JSON, verify exactly what's stored.
+
+---
+
+### 12. How do I integrate this into my existing agent?
+
+Three steps. First, birth a soul: `soul = await Soul.birth("Name", engine=YourEngine())`. Second, call `soul.observe(Interaction(user_input=..., agent_output=...))` after each exchange -- this runs the full psychology pipeline (sentiment, significance, fact extraction, self-model update). Third, use `soul.to_system_prompt()` to inject the soul's personality and relevant memories into your agent's system prompt, and `soul.recall(query)` to retrieve specific memories. The soul produces identity data. Your agent framework handles everything else. Works with LangChain, LlamaIndex, custom agents, or bare API calls.

soul_protocol-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OCEAN Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.