❤️ Soulmate

A local-first AI reasoning agent with persistent memory

Soulmate gives your AI agent a structured mind — a 9-phase reasoning loop, 3-layer persistent memory, a recursive knowledge graph, and guard hooks that prevent grinding. It works with Cascade/Windsurf, Ollama, or any OpenAI-compatible backend.

100% local. 100% free. No API keys required.

What Soulmate Does

Most AI coding assistants are stateless — they forget everything between sessions. Soulmate fixes this:

• Persistent Memory — Remembers your profile, projects, preferences, and past learnings across sessions
• 9-Phase Reasoning Loop — Classify, Define Done, Evidence, Decide, Act, Verify, Repair, Synthesize, Judge, Report
• Recursive Knowledge Graph — Facts, skills, and concepts linked with bidirectional edges. Multi-hop traversal finds connections that flat memory can't
• Guard Hooks — Spawn guard prevents over-delegation, fail streak detector stops grinding after 3 failures
• Domain Adapters — Specialized reasoning for coding, planning, math, analysis, literature, and factual tasks
• RML Engine — Reinforcement Meta-Learning tunes prompt parameters based on outcomes
• Autonomous Skill Creation — Detects repeatable patterns and creates reusable skills

Quick Start

Install

pip install soulmate-ai

Use with Cascade/Windsurf

soulmate-cascade-install

This installs:

• 7 skill files in ~/.windsurf/skills/
• 4 guard hooks in ~/.windsurf/hooks/
• A workflow file for /soulmate slash command
• Memory bridge files in ~/.soulmate/ (MEMORY.md, SOUL.md)

Use with Ollama

1. Make sure Ollama is running with at least one model
2. Start the server:

soulmate-server

3. Send tasks:

curl -X POST http://localhost:8080/v1/complete \
  -H "Content-Type: application/json" \
  -d '{"query": "How should I architect a real-time chat system?", "thread_id": "my-project"}'

The 9-Phase Reasoning Loop

3-Layer Memory

Guard Hooks

• SessionStart — Injects reasoning discipline, loads profile and routing
• SpawnGuard (PreToolUse) — Blocks unnecessary delegation, enforces plan gate
• FailStreak (PostToolUse) — After 3 failures, injects attribution ladder: harness, deployment, product
• SessionEnd — Logs session summary to episodic memory

Configuration

Create ~/.soulmate/config.yaml:

provider_backend: ollama

models:
  fast: "qwen3:1.7b"
  base: "qwen2.5-coder:7b"
  judge: "glm4:9b-chat"
  code: "qwen2.5-coder:7b"
  style: "qwen2.5-coder:3b"

harness:
  max_loops: 6
  default_confidence_threshold: 0.85

Testing

pip install -e ".[dev]"
pytest

286 tests covering all core modules.

Requirements

• Python 3.10+
• Ollama (for local LLM backend) or any OpenAI-compatible API
• Optional: Cascade/Windsurf IDE for full integration

License

MIT — see LICENSE

Author

singularitycurse26-svg

Support the Project

If Soulmate helps you, consider supporting development: