Metadata-Version: 2.4
Name: slowave
Version: 0.1.11
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: torch>=2.2
Requires-Dist: faiss-cpu>=1.7
Requires-Dist: click<9,>=8.1
Requires-Dist: sentence-transformers>=2.7
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

**Brain-inspired, latent-space long-term memory for MCP-compatible AI agents, coding assistants, and chats.  
Shared across sessions, clients, and tools.**

[![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 plugs into **Claude Code**, **Cline**, **Claude Desktop**, and more through MCP, giving them a shared local memory that accumulates, consolidates, adapts, and recalls across sessions.

Slowave is not just a transcript store or a conventional RAG layer. It is inspired by the idea that memory is a dynamic system shaped by association, time, salience, replay, and retrieval. The default memory path uses local embeddings, SQLite, FAISS, deterministic geometry, and background consolidation — without requiring an LLM call in the core memory loop.

> **Slowave core idea:** sessions create episodes, replay distills recurring patterns, time changes salience, contradiction-aware updates keep memory current, recall reinforces memories that prove useful, and procedural memories can capture reusable workflows that worked before.

Most agent memory systems do one of two things: append your conversations to a Markdown file, or ask an LLM to rewrite your notes every turn. Both quietly accumulate stale text, forget context across sessions, or burn API calls on bookkeeping. Slowave does neither.

| What most systems do | What Slowave does instead |
|---|---|
| Append to a Markdown file or flat vector store | Form structured episodes from live events |
| Ask an LLM to summarise or rewrite memories | No LLM in the memory loop — ever |
| Return the same stale text on every query | Memories reinforce, decay, and reshape over time |
| Dump conversation history into the prompt | Inject a compact, cue-relevant brief via `slowave_context` |
| Start fresh every session | Cross-session memory that persists, consolidates, and evolves |
| Siloed to one tool | One shared memory store across all your AI clients |

## ✨ At a glance

| What you get | Why it matters |
|---|---|
| **No LLM in the core memory loop** | No API key, cloud extraction step, or per-query model call required. Memory ingest, consolidation, and retrieval are all LLM-free. |
| **Privacy-first local memory** | Memory is stored and processed locally; no cloud memory backend, API extraction step, or remote LLM inference is required. |
| **Local CPU inference** | Uses BAAI/bge-small-en-v1.5 embeddings, SQLite, FAISS, and deterministic geometry. |
| **Brain-inspired consolidation** | Raw events become episodes; episodes replay into prototypes; prototypes consolidate into latent schemas. |
| **Active recall** | Retrieved memories are reinforced, so recall changes the memory system over time. |
| **Procedural memory** | Slowave can retrieve reusable workflows for familiar goals and situations, not only static facts. Procedures are deterministic, feedback-shaped, and scope-aware without being locked to one project. |
| **Time-aware memory** | Salience, decay, temporal anchors, supersession, and contradiction-aware updates help keep memory current. Episodes are date-stamped (ISO 8601) and recalled with temporal context. |
| **Gated working memory** | `slowave_context` injects a compact, cue-relevant brief instead of dumping history into the prompt. |

```mermaid
flowchart LR
    A([💬 Events]) -->|session end| B([🧠 Episodes])
    B -->|replay| C([🌀 Prototypes])
    C -->|consolidation| D([📖 Schemas])
    D -->|recall/context| E([⚡ Context brief])
    P([🧭 Procedures]) -->|goal/situation score| E
    E -->|agent uses memories| F([✅ Feedback])
    E -.->|reinforces| B
    E -.->|reinforces| C
    F -.->|reinforces / suppresses / review| D
    F -.->|confidence / success / failure| P

    style A fill:#2d4a3e,stroke:#4caf87,color:#e8f5e9
    style B fill:#1a3a5c,stroke:#4a9eff,color:#e3f0ff
    style C fill:#3a2d5c,stroke:#9b7fee,color:#f0ebff
    style D fill:#4a2d1a,stroke:#ff9944,color:#fff3e0
    style E fill:#1a3a2d,stroke:#44cc88,color:#e8f5e9
    style F fill:#4a1a2d,stroke:#ff6699,color:#fff0f5
```

## ⚙️ How it works

1. You work with your AI client (Claude Code, Cline, Claude Desktop, or any MCP-compatible tool) on a task.
2. The client logs observations through MCP as the work happens.
3. When the session ends, Slowave forms an episode from those events.
4. The background worker consolidates episodes into prototypes and latent schemas.
5. In a future session, `slowave_context` injects a compact, cue-relevant memory brief and, when available, matching procedural memories for the current goal/situation.
6. Recalled memories and procedures are reinforced or suppressed by explicit retrieval feedback.

Slowave can remember project conventions, architectural decisions, personal preferences, debugging lessons, open questions, constraints, reusable procedures, and any context that should survive across sessions — for coding work and general chat alike. `project` is a convenience alias for the more generic `scope` concept, e.g. `scope="project:slowave"`, `scope="domain:cooking"`, or `scope="relationship:alex"`.

## 🚀 Install

```bash
pipx install slowave
slowave setup
```

`slowave setup` detects your platform, wires every client it finds (Claude Code, Cline, Claude Desktop), injects lifecycle instructions, and installs the background worker — all in one shot. It is idempotent: safe to re-run.

```bash
slowave doctor   # verify: checks Python, torch, faiss, embedding backend
slowave stats    # shows stored events, episodes, and schemas
```

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

> [!IMPORTANT]
> **Claude Desktop:** after `slowave setup`, paste the lifecycle block into **Settings → General → Instructions for Claude**. `slowave setup` prints the required settings path and link. See [docs/install.md → Step 2a](docs/install.md#step-2a--claude-desktop-add-custom-instructions).

**Full install guide** (all install methods, manual config, per-client setup, worker, troubleshooting): **[docs/install.md](docs/install.md)**

## 📊 Local dashboard

Run a read-only web UI for memory inspection:

```bash
slowave dashboard
# open http://127.0.0.1:8765
```

The dashboard binds to `127.0.0.1` by default and shows DB health, Slowave/MCP processes, schemas, a recall playground, and a schema graph.

## ⌨️ CLI usage

The CLI is useful for debugging, manual memory writes, dashboard access, and benchmark/research workflows. It should not be the first path for most users; real agent memory needs MCP plus prompt/rules injection.

See [docs/cli.md](docs/cli.md) for the command list and a CLI-only quickstart.

## 📚 Documentation

| Guide | Covers |
|---|---|
| [docs/install.md](docs/install.md) | **Install, setup, and per-client wiring** — the single authoritative guide |
| [integrations/](integrations/) | Per-client quick-ref cards (Claude Desktop, Claude Code, Cline) |
| [docs/cli.md](docs/cli.md) | CLI command reference |
| [docs/dashboard.md](docs/dashboard.md) | Local dashboard guide |
| [docs/architecture.md](docs/architecture.md) | Brain-inspired mechanisms, data flow, storage, recall, consolidation |
| [docs/design.md](docs/design.md) | Why the LLM path was removed from the memory loop |
| [docs/benchmarks.md](docs/benchmarks.md) | Benchmark results, run conditions, per-category breakdown |
| [docs/limitations.md](docs/limitations.md) | Known limitations: schema quality, language support, scale |
| [docs/reproducibility.md](docs/reproducibility.md) | How to reproduce benchmark numbers |

## 📈 Benchmarks

> **Alpha-stage numbers.** Internal runs, not independently verified. Treat as directional. See [docs/benchmarks.md](docs/benchmarks.md) for full run conditions and known gaps.

**All runs: brain-only path, local CPU, BAAI/bge-small-en-v1.5 embeddings, SQLite + FAISS, zero LLM calls.**

Two modes are reported. The **with-consolidation** numbers (70.0% / 82.7%) represent the full Slowave pipeline: sessions → episodes → replay → latent schemas → recall. The **episode-only baseline** (60.2% / 74.6%) is retrieval without consolidation — episodes recalled directly, no schemas. The difference shows the contribution of the consolidation layer.

### Overall results

| Benchmark | Questions | With consolidation | Episode-only baseline | Cosine-only ablation¹ |
|---|---:|---:|---:|---:|
| LongMemEval | 500 | **70.0%** | 60.2% | ~60.0% |
| LoCoMo | 1 986 | **82.7%** | 74.6%² | ~68.0% |

*Metric: keyword hit-rate. All runs: zero LLM calls, ~10 ms recall latency, data on device.*

¹ Cosine-only ablation: spreading activation, graph expansion, and transition model all disabled.  
² LoCoMo is multi-session by design; episode retrieval already captures a strong signal. Full latent consolidation improves the internal keyword hit-rate mainly through temporal, commonsense, single-session, and adversarial categories.

### Original MemGPT DMR source candidate

The repo tracks the likely original MemGPT DMR source data from `MemGPT/MSC-Self-Instruct`: 500 MSC self-instruct records. Slowave retrieves answer-bearing context for **455/500 = 91.0%** with zero LLM calls.

The original-candidate score is a retrieval-context keyword hit-rate, not yet the published MemGPT/Zep generated-answer + LLM-judge protocol.

| System | Score | LLM calls | Cost |
|---|---:|---|---|
| **Slowave on original DMR source candidate** | **91.0%** | **0** | **$0.00** |
| Zep reported DMR baseline (published generated-answer + LLM judge) | 94.8% | Many | $ |
| MemGPT reported DMR baseline (published generated-answer + LLM judge) | 93.4% | Many | $ |

Slowave is strong on factual recall with zero API cost and ~10–12 ms recall latency. Do not treat this as an apples-to-apples published DMR leaderboard until the generated-answer + LLM-judge protocol is implemented.

### LongMemEval per-category (with consolidation)

| Category | Score | Notes |
|---|---:|---|
| Single-session-user | **91.4%** | ✅ strong |
| Knowledge-update | **92.3%** | ✅ strong |
| Single-session-assistant | **66.1%** | ✅ solid |
| Temporal-reasoning | **67.7%** | ✅ solid |
| Multi-session | 60.9% | ⚠ number aggregation gap |
| Single-session-preference | 20.0% | ⚠ preference abstraction gap |

### LoCoMo per-category (with consolidation)

| Category | Score | Notes |
|---|---:|---|
| Adversarial | **95.1%** | ✅ robust against distractors |
| Multi-session | **84.9%** | ✅ strong cross-session recall |
| Single-session | **80.9%** | ✅ strong |
| Temporal | **68.2%** | ✅ improved, still not date-arithmetic complete |
| Commonsense | 60.4% | ⚠ improved but still partly outside stored-memory retrieval |

### Known gaps

| Gap | Root cause | Status |
|---|---|---|
| Temporal date arithmetic | "How many days between X and Y?" requires arithmetic, not retrieval | Open — answer-construction layer |
| Multi-session aggregation (LME 60.9%) | Summing quantities across episodes — no single episode holds the answer | Open — explicit aggregation layer |
| Preference abstraction (LME 20%) | Implicit preferences not abstracted into queryable schema entries | Open — preference-extraction layer |

### Language support

**All core memory operations are language-agnostic** — episode storage, embedding, retrieval, FAISS search, salience, spreading activation, the prototype graph, and multi-scale consolidation work on embedding vectors and numeric metadata with no language dependency.

**Two components are English-only:**

| Component | English-only reason | Fallback for non-English |
|---|---|---|
| **Temporal anchor probe (Stage 10)** | Pre-embedded English landmark phrases ("last month", "two weeks ago") calibrate the temporal compass | Temporal re-ranking defaults to "now" — correct for atemporal queries, slightly suboptimal for past-anchored ones |
| **VSA dep-parse mode (`vsa_mode="ner"`)** | Uses spaCy `en_core_web_sm` dependency parser for subject/predicate/object role extraction | Use `vsa_mode="geometric"` (default, language-agnostic) or `vsa_mode="lexical"` (regex-based, no model dependency) |

The temporal probe phrase list is in `slowave/latent/temporal.py` (`_TEMPORAL_PROBES`). Adding phrases in other languages extends the compass to those languages without any other code change.

For a full language support matrix and multi-language deployment guide, see [docs/limitations.md](docs/limitations.md).

For full per-category results, run conditions, and known gaps see [docs/benchmarks.md](docs/benchmarks.md).  
For evaluation scripts and reproduction steps see [docs/reproducibility.md](docs/reproducibility.md).  
For known limitations see [docs/limitations.md](docs/limitations.md).

## Contributing, licensing, and commercial use

Slowave is open source and released under the GNU Affero General Public License v3.0 or later.

The AGPL license is intentional: Slowave is designed as a memory engine that may be embedded in agents, tools, and networked systems, and the license helps ensure that improvements to the open core remain available to the community.

Commercial licensing may be offered in the future for organizations that want to embed, distribute, or operate Slowave under different terms.

Contributions are welcome, especially:

- bug reports;
- installation feedback;
- documentation improvements;
- tests and evaluation scripts;
- integration examples;
- recall and retrieval quality reports;
- small, focused code improvements.

Before opening a pull request, please read [CONTRIBUTING.md](./CONTRIBUTING.md).

Substantial code contributions may require acceptance of a Contributor License Agreement, or CLA, before merging. This helps keep Slowave open source while preserving the option for future commercial licensing.

