Metadata-Version: 2.4
Name: slowave
Version: 0.4.9
Summary: Brain-inspired long-term memory for AI agents — zero LLM during ingest or retrieval
Author: mrsalty
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/mrsalty/slowave
Project-URL: Repository, https://github.com/mrsalty/slowave
Project-URL: Issues, https://github.com/mrsalty/slowave/issues
Project-URL: Changelog, https://github.com/mrsalty/slowave/releases
Keywords: memory,agent,ai,mcp,neuroscience,rag,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26
Requires-Dist: faiss-cpu>=1.7
Requires-Dist: click<9,>=8.1
Requires-Dist: onnxruntime<2.0,>=1.16
Requires-Dist: transformers>=4.30
Requires-Dist: huggingface-hub>=0.16
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: spacy>=3.8.14
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# Slowave

**A second brain for your AI, shared across every tool.**

[![PyPI](https://img.shields.io/pypi/v/slowave?color=2f6f4e)](https://pypi.org/project/slowave/)
[![Python](https://img.shields.io/pypi/pyversions/slowave?color=4c6f91)](https://pypi.org/project/slowave/)
[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)

Slowave gives your AI tools a central, private, local second-brain that: 
- persists across sessions
- persists across tools
- reduce your token usage (~86%)
- evolves over time
- costs 0$ (no LLM in the loop)
- runs on your CPU

```
┌────────────┐   work with   ┌─────────────┐
│            │ ────────────▶ │ Claude Code │ ◀───┐
│            │               └─────────────┘     │    (mcp)
│    You     │               ┌─────────────┐     │    context         ┌────────────┐
│  (local)   │ ────────────▶ │    Cline    │ ◀───┼──▶ remember  ◀───▶ │  Slowave   │◀──────┐
│            │               └─────────────┘     │    recall          │  (local)   │       │
│            │               ┌─────────────┐     │    procedure       └─────┬──────┘       │
│            │ ────────────▶ │   Cursor    │ ◀───┘    feedback              │ evolves      │
└────────────┘               └─────────────┘                                │ decays       │
                                                                            │ reinforces   │
                                                                            │ consolidates │
                                                                            │ learns       │
                                                                            │ workflows    │
                                                                            └──────────────┘                 
```


## Why Slowave?

**👊 One memory, every AI tool.**  
Claude Code, Cline, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client share the same local memory store. Fix a bug in Claude Code tonight — Cline knows the lesson tomorrow. Decide on an architecture in Claude Desktop — it surfaces in your next coding session. Context follows you across tools instead of dying when you close a chat.

**🧠 Adaptive memory, not static notes.**  
Most AI memory is a pile of Markdown. Slowave behaves more like a brain: frequently recalled memories strengthen, stale ones fade, contradicted facts get superseded automatically. You never manually clean up a `MEMORY.md` file again.

**⚙️ Procedural memory: workflows that stick.**  
Slowave stores reusable procedures — "how we do deploys in this repo", "steps to implement a new feature across projects" or simply "how this spaghetti recipe should be cooked".  Recall them by goal and situation, not by keyword search. Your agents learn habits, not just facts.

**🔒 Fully local, zero LLM calls.**  
Ingestion, consolidation, and recall run on your machine using embeddings, FAISS, and SQLite — no LLM in the memory loop, no API key, no data sent to a cloud memory backend. Memory operations cost $0 per query and work offline.

**💰 86% fewer tokens than replaying history.**  
Slowave injects a compact working-memory brief instead of accumulating the full conversation. Over 20 sessions, raw history grew from **96 → 1,875 tokens** while Slowave stayed flat at **~136 tokens** — with **95% recall quality** (the right memory surfaced in 19/20 sessions). Crossover happens at session 2. Measured with the real semantic encoder, not claimed. [See the test →](docs/token_efficiency.md)

## Install

```bash
pipx install slowave
slowave setup           # automated configuration
```

`slowave setup` detects your platform, wires every client it finds, injects lifecycle hooks, and starts the background worker. **Idempotent** and safe to re-run. See [what gets modified →](docs/slowave_setup.md)

> [!IMPORTANT]
> **Claude Desktop:** after setup, paste the lifecycle block into **Settings → General → Instructions for Claude**.
> **Cursor:** after setup, paste the lifecycle block into **Settings → Rules for AI**.
> `slowave setup` prints the exact text and location for both. All other clients (Cline, Claude Code, Windsurf) are fully automated.

```bash
slowave doctor   # verify installation
slowave stats    # memory snapshot
```

Memory is stored at `~/.slowave/slowave.db`. No Ollama, no vector database, no cloud service required.

**[Full install guide →](docs/install.md)**

## What Slowave remembers

Anything that should survive across sessions: preferences, decisions, constraints, lessons learned, open questions, and reusable workflows — for work, research, or personal use. Each memory carries a timestamp, decays if never recalled, and strengthens when it proves useful. Contradictions are detected geometrically and old facts are superseded automatically — no LLM required.

Memory is scoped flexibly: `project:my-app`, `domain:cooking`, `relationship:alex` — or unscoped for universal context.

## Benchmarks

> Alpha-stage numbers. Internal runs, not independently verified. See [docs/benchmarks.md](docs/benchmarks.md) for per-category results, ablation details, and known gaps.

Numbers from the **clean ablation sweep** (17 variants, strict sample-size validation, zero LLM calls throughout). Full system = salience reranking + episodic consolidation enabled.

| Benchmark |    n | Cosine baseline | Full system | Δ | LLM calls |
|---|-----:|---:|---:|---:|---|
| LongMemEval |  500 | 87.6% | **87.8%** | +0.2 pp (saturation) | 0 |
| LoCoMo | 1986 | 72.1% | **83.5%** | **+11.4 pp** | 0 |
| DMR (MSC Self-Instruct) |  500 | **93.6%** | 88.0% | −5.6 pp ⚠ | 0 |
| StaleMemory (concrete attrs) |  900 | — | **86–89%** detection | — | 0 |

⚠ **DMR note:** The full system's −5.6 pp on DMR is a protocol artefact — DMR uses keyword-overlap scoring, which penalises salience reranking and schema consolidation (abstractions that improve recall on conversational queries but reduce raw keyword matches). The cosine-only baseline (93.6%) is the fair DMR headline.

## Documentation

|                                                      |                                                                |
|------------------------------------------------------|----------------------------------------------------------------|
| [docs/design](docs/design.md)                        | the brain-inspired rationale behind Slowave                    |
| [docs/architecture.md](docs/architecture.md)         | How memory consolidation works                                 |
| [docs/install.md](docs/install.md)                   | Install, setup, per-client wiring, troubleshooting             |
| [docs/slowave_setup.md](docs/slowave_setup.md)       | `slowave setup` command help                                   |
| [docs/manual_setup.md](docs/manual_setup.md)         | Step-by-step manual configuration guide                        |
| [docs/benchmarks.md](docs/benchmarks.md)             | Per-category results, known gaps, reproducibility              |
| [docs/token_efficiency.md](docs/token_efficiency.md) | Token efficiency vs. history replay and static knowledge files |
| [docs/limitations.md](docs/limitations.md)           | Honest limits: scale, language, unsolved categories            |
| [docs/cli.md](docs/cli.md)                           | CLI reference                                                  |
| [docs/dashboard.md](docs/dashboard.md)               | Local web UI (`slowave dashboard`)                             |

## Dashboard

Keep Slowave always under control through the local dahsboard.

![dashboard.png](img/dashboard.png)

You use it, Slowave will start connecting the dots

![dashboard_graph.png](img/dashboard_graph.png)

## Contributing

Slowave is open source under AGPL-3.0-or-later. Bug reports, install feedback, and focused improvements are welcome — read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR. Commercial licensing terms may be offered in the future.
