Metadata-Version: 2.4
Name: slowave
Version: 0.5.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
Provides-Extra: test
Requires-Dist: pytest>=9.0.3; extra == "test"
Requires-Dist: faiss-cpu>=1.7; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: faiss-cpu>=1.7; 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/badge/python-3.10%2B-4c6f91)](https://pypi.org/project/slowave/)
[![PyPI Status](https://img.shields.io/pypi/status/slowave?color=orange)](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  
👉 reduces your token usage  
👉 evolves over time  
👉 costs $0 — no LLM in the loop  
👉 runs on your CPU  


## Why try Slowave?

Most AI tools forget everything when the session ends.

That means you keep repeating the same context:

- how your project is structured;
- how tests and releases work;
- what decisions were already made;
- what preferences you have;
- what previous debugging sessions discovered;
- what should no longer be suggested.

Slowave gives AI tools a shared local memory layer.

It lets coding assistants, agents, chat clients, and MCP-compatible tools retrieve relevant context from previous sessions without replaying full history into every prompt.

Slowave is useful if you want:

- persistent memory across sessions;
- shared memory across multiple AI tools;
- local-first storage;
- no LLM calls in the memory loop;
- scoped project memory;
- adaptive recall with reinforcement, decay, and supersession;
- compact working-memory briefs instead of huge pasted context blocks.

In short:

> Slowave helps AI tools stop starting from zero.


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

## Install

```bash
pipx install slowave
slowave setup --dry-run
slowave setup
slowave doctor
```

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

> [!NOTE]
> The default text encoder downloads its model from HuggingFace on first use (~45 MB); subsequent runs work fully offline.

> [!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.

**Privacy:** Slowave stores all memory (facts, episodes, embeddings, logs) locally in a plain SQLite database file. No memory leaves your machine — it's never sent to a cloud service, and the database file is unencrypted (you can inspect it with SQLite tools). If you store sensitive information, protect the database file using OS-level permissions or full-disk encryption.

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

## What makes Slowave different?

**👊 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 just notes or a vector index.**  
Slowave memory changes with use: useful memories are reinforced, stale ones decay, and outdated ones can be superseded. Recall is shaped by salience, time, scope, and feedback — not just raw vector similarity.

**⚙️ 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. 

**💰 Compact context instead of history replay.**  
Slowave injects a small working-memory brief instead of replaying full chat history. In internal tests, this reduced context size by 86% over 20 sessions while preserving high recall quality. [See the test →](docs/token_efficiency.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, known gaps, and reproducibility.

On **fact-recall benchmarks**, Slowave reaches scores competitive with LLM-based memory systems — **with zero LLM calls**. Gaps remain in implicit preference inference and behavioral style drift, which require LLM reasoning that Slowave deliberately avoids. [See known gaps →](docs/limitations.md)

| Benchmark |    n | Slowave | Published / reported comparator | Slowave LLM calls |
|---|-----:|---:|---|:---:|
| LoCoMo (multi-session recall) | 1 986 | **81%** | Zep 75.1% · LangMem 58.1% · GPT-4 fine-tuned ~76% | **0** |
| LongMemEval (full haystack) | 500 | **93.4%** | Mem0 94.4%† | **0** |
| StaleMemory — concrete preference drift‡ | 900 | **86–89%** | no published baseline | **0** |

> † Mem0 uses GPT-5 as judge; Slowave uses keyword-overlap. The 1 pp LME gap falls within the expected difference between these two scoring protocols — the gap would likely narrow on the same scorer, but this has not been directly measured. The LoCoMo gap is large enough to hold across any reasonable scorer. All Slowave runs: zero LLM calls, fully local. [Full methodology →](docs/benchmarks.md)
>
> ‡ Concrete-keyword subset of 1,200 total StaleMemory scenarios. Abstract behavioral drift (the remaining 300 scenarios) scores 0–1% — a structural limit of retrieval-only systems. [See known gaps →](docs/limitations.md)

## How Slowave compares

Most agent-memory systems focus on extracting and retrieving memories for an LLM-based agent. Slowave takes a different path: it is a local, MCP-native memory substrate where the memory lifecycle itself — recall, reinforcement, decay, supersession, feedback, and procedural reuse — runs without an LLM in the loop.

|  | MEMORY.md | Plain RAG | Mem0 / Zep / Graphiti | Letta / LangMem | **Slowave** |
|---|:---:|:---:|:---:|:---:|:---:|
| Persistent across sessions | ✅ | ✅ | ✅ | ✅ | ✅ |
| Shared across MCP tools | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ✅ |
| Local-first by default | ✅ | ✅ | ⚠️ | ⚠️ | ✅ |
| Adaptive recall over time | ❌ | ❌ | ⚠️ | ⚠️ | ✅ |
| Reinforcement / decay without LLM calls | ❌ | ❌ | ❌ | ❌ | ✅ |
| Supersession / stale-memory handling | ❌ | ❌ | ✅ | ⚠️ | ✅ |
| Procedural memory / workflows | ⚠️ | ❌ | ⚠️ | ✅ | ✅ |
| Zero memory API cost | ✅ | ✅ | ❌ | ⚠️ | ✅ |

> ✅ = native or central capability.  
> ⚠️ = possible, partial, backend-dependent, or LLM-mediated.  
> ❌ = not a primary/default capability.


## Dashboard

Keep Slowave always under control through the local dashboard.

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

You use it, Slowave will start connecting the dots

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

## 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, strengths, 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)           | Capability gaps, design trade-offs, deployment limits          |
| [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.
