Metadata-Version: 2.4
Name: slowave
Version: 0.4.1
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 you use.**

[![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 private, local memory that persists across sessions, evolves over time, and costs nothing to run — no API key, no LLM calls, no data leaving your machine.

## Why Slowave?

**👊 One memory for every AI tool.**  
Claude Code, Cline, Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients all share the same local memory store. Your context follows you across tools, sessions, and workflows instead of being trapped inside one chat.

**🌱 Memory that evolves with you.**  
Slowave does not just pile up notes. Frequently recalled memories become stronger, stale information fades, and contradicted facts can be superseded. The result is a memory system that stays useful over time without constant manual cleanup.

**💰 Save tokens instead of replaying history.**  
Slowave replaces unbounded chat-history replay with a compact working-memory brief. In a 10-session test, raw history grew from **93 → 962 tokens**, while Slowave stayed constant at around **103 tokens** — roughly **80% fewer tokens**. Measured, not claimed. [See the test →](docs/token_efficiency.md)

**🔒 Zero LLM calls in the memory loop.**  
Ingestion, consolidation, and recall run locally using embeddings, FAISS, SQLite, and deterministic geometry — not an LLM. No API key is required, and no cloud memory backend is needed by default.

## Install

```bash
pipx install slowave
slowave setup           # automated configuration
slowave setup --dry-run # preview changes first
slowave doctor          # verify installation
```

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

**Uninstall:**
```bash
slowave cleanup         # remove all configuration
pipx uninstall slowave  # remove package
```

> [!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, run conditions, and known gaps.

| Benchmark | n | Score | LLM calls |
|---|---:|---:|---|
| LongMemEval | 500 | **87.6%** | 0 |
| LoCoMo | 1 986 | **77.6%** (F1 0.723) | 0 |
| DMR (MSC Self-Instruct) | 500 | **86–87%** | 0 |
| StaleMemory | 1 200 | **37.4% detection** | 0 |

*Latest full-suite runs: `data/runs/2026-06-06_full` and `data/runs/2026-06-06_rerun`. Keyword hit-rate metric except StaleMemory detection; local Mac M-series CPU; no API key.*

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

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