Metadata-Version: 2.4
Name: soulmate-ai
Version: 1.0.0
Summary: Soulmate — A local-first AI reasoning agent with persistent memory, 9-phase reasoning loop, and recursive knowledge graph
Author: singularitycurse26-svg
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cascade,local,memory,ollama,reasoning,soulmate,windsurf
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: chromadb>=0.4.22
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: langgraph>=0.0.40
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: sentence-transformers>=2.3.0
Requires-Dist: sse-starlette>=1.8.0
Requires-Dist: uvicorn[standard]>=0.24.0
Provides-Extra: dev
Requires-Dist: httpx[test]>=0.25.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# ❤️ Soulmate

### A local-first AI reasoning agent with persistent memory

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests: 286](https://img.shields.io/badge/tests-286%20passing-brightgreen.svg)](#)
[![Ollama](https://img.shields.io/badge/Ollama-compatible-orange.svg)](https://ollama.ai)

<img src="assets/soulmate.jpg" width="200" alt="Soulmate Heart Logo" />

**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](https://windsurf.com), [Ollama](https://ollama.ai), or any OpenAI-compatible backend.

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

</div>

---

## 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

```bash
pip install soulmate-ai
```

### Use with Cascade/Windsurf

```bash
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](https://ollama.ai) is running with at least one model
2. Start the server:

```bash
soulmate-server
```

3. Send tasks:

```bash
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

| Phase | What It Does |
|-------|-------------|
| **Classify** | Is this trivial, a question, a task, or needs planning? |
| **Define Done** | What does success look like? How will it be verified? |
| **Evidence** | Gather facts from primary sources. Don't guess. |
| **Decide** | Synthesize evidence into ONE recommendation. Name alternatives. |
| **Act** | Make the smallest correct change. State INTENT before editing. |
| **Verify** | Run the check. Don't infer success — observe it. |
| **Repair** | If verification fails, fix the root cause. Don't patch symptoms. |
| **Synthesize** | Combine findings into a coherent answer. |
| **Judge** | Adversarial review. Check for unverified claims. Assign confidence. |
| **Report** | Outcome-first: result, then reasoning, then caveats. |

## 3-Layer Memory

| Layer | Storage | Purpose |
|-------|---------|---------|
| **Working** | Context window | Current session state, sacred zone for critical context |
| **Episodic** | SQLite | Session trajectories with timestamps. Decays over 30 days. |
| **Semantic** | Knowledge graph + ChromaDB | Skills, facts, concepts with bidirectional recursive links |

## 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`:

```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

```bash
pip install -e ".[dev]"
pytest
```

286 tests covering all core modules.

## Requirements

- Python 3.10+
- [Ollama](https://ollama.ai) (for local LLM backend) or any OpenAI-compatible API
- Optional: [Cascade/Windsurf](https://windsurf.com) IDE for full integration

## License

MIT — see [LICENSE](LICENSE)

## Author

[singularitycurse26-svg](https://github.com/singularitycurse26-svg)

## Support the Project

If Soulmate helps you, consider supporting development:

<div align="center">

[![Donate](https://img.shields.io/badge/PayPal-Donate-red.svg?logo=paypal)](https://paypal.me/soulmate4)

</div>

<div align="center">

Built with love for the local-first AI community

</div>
