slowave 0.1.3__tar.gz

slowave-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrsalty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slowave-0.1.3/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: slowave
+Version: 0.1.3
+Summary: Brain-inspired long-term memory for AI agents — zero LLM during ingest or retrieval
+Author: mrsalty
+License: MIT
+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: 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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: faiss-cpu
+Requires-Dist: click>=8.1
+Requires-Dist: sentence-transformers
+Requires-Dist: mcp[cli]
+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"
+Dynamic: license-file
+
+# Slowave
+
+**Brain-inspired long-term memory for AI agents and desktop AI chats.** Slowave plugs into Claude Code, Cline, and Claude Desktop through MCP, giving them a shared memory that accumulates, consolidates, adapts, and recalls across sessions.
+
+Slowave's core thesis is simple: **language is not the memory system; language is one interface to it.** The memory engine works in latent space, the way brains appear to operate over distributed internal representations rather than over transcripts. Text is embedded once, then memory evolves through geometry, time, salience, replay, and activation. The default path uses **no LLM for ingest, consolidation, or recall**: inference is local, fast, CPU-friendly, private, and independent of any model provider.
+
+Critical features:
+
+- **No LLM in the core memory loop** — no API key, no cloud extraction step, no per-query model call.
+- **Local CPU inference** — BAAI/bge-small-en-v1.5 embeddings, SQLite, FAISS, and deterministic geometry.
+- **Brain-inspired consolidation** — raw events become episodes, episodes replay into prototypes, prototypes become latent schemas.
+- **Recall changes memory** — retrieved memories are reinforced; recall is an active operation, not a passive database lookup.
+- **Time-aware memory** — salience, decay, temporal anchors, supersession, and contradiction handling keep memory current.
+- **Generic ingestion** — not code-assistant-specific; it can remember coding work, planning, preferences, decisions, chat context, or any text interaction.
+- **Gated working memory** — `slowave_context` injects only a compact, cue-relevant memory brief instead of dumping history into the prompt.
+- **Provenance and inspection** — schemas trace back to episodes/raw events; the local dashboard exposes memory health and recall behavior.
+
+## What Slowave is for
+
+Slowave is a local long-term memory substrate for tools that otherwise forget between sessions. It is useful when you want an AI assistant to remember:
+
+- project conventions and architectural decisions;
+- personal preferences and communication style;
+- recurring workflows and commands;
+- previous debugging sessions and lessons learned;
+- open questions, warnings, constraints, and artifacts;
+- non-coding chat context from desktop AI conversations.
+
+It is intentionally not just a RAG layer. Existing memory systems usually retrieve stored text or ask an LLM to rewrite memories. Slowave treats memory as a living system: sessions create episodes, replay distills patterns, time changes salience, contradiction updates beliefs, and recall itself reinforces what was useful.
+
+## Install in minutes
+
+Slowave is a local memory service. Installing the package gives you two commands:
+
+- `slowave`: CLI, dashboard, manual recall/debugging.
+- `slowave-mcp`: MCP server used by Claude Desktop, Claude Code, and Cline.
+
+```bash
+brew tap mrsalty/slowave
+brew install slowave
+```
+
+PyPI publishing is not enabled yet, so `pip install slowave` / `pipx install slowave` will not work until the package is published to PyPI. If you are not using Homebrew, install from source:
+
+```bash
+git clone https://github.com/mrsalty/slowave
+cd slowave
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Verify:
+
+```bash
+which slowave-mcp
+slowave --help
+slowave-mcp --help
+slowave stats
+```
+
+Then choose your client and follow the short guide:
+
+| Client | Setup guide |
+|---|---|
+| Claude Desktop | [integrations/claude-desktop/](integrations/claude-desktop/) |
+| Claude Code | [integrations/claude-code/](integrations/claude-code/) |
+| Cline | [integrations/cline/](integrations/cline/) |
+
+**Important:** MCP setup alone is not enough. Every client needs:
+
+1. MCP configuration so the `slowave_*` tools are visible.
+2. Instruction/rules injection so the client actually calls Slowave during the task.
+3. A background worker for ongoing consolidation into distilled schemas.
+
+Episodes are created immediately when a session ends. The worker is what turns accumulated episodes into durable latent schemas for better future `slowave_context` injection.
+
+The integration guides contain the exact MCP JSON, prompt/rules block, worker setup, and verification command for each client. Start at [integrations/](integrations/) if you are unsure.
+
+Default storage: `~/.slowave/slowave.db`. No Ollama, OpenRouter, or other LLM backend is required for the default brain-only path.
+
+## Local dashboard
+
+Run a local 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, 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
+
+| | |
+|---|---|
+| [integrations/](integrations/) | Fast client-specific setup guides for Claude Desktop, Claude Code, and Cline |
+| [docs/install.md](docs/install.md) | Install, MCP setup, prompt/rules injection, verification |
+| [docs/agents.md](docs/agents.md) | MCP tool behavior and lifecycle for Claude Code, Cline, Claude Desktop |
+| [docs/agent-enforcement.md](docs/agent-enforcement.md) | Copy/paste prompt templates that make clients call Slowave consistently |
+| [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/dashboard.md](docs/dashboard.md) | Local dashboard guide |
+| [docs/cli.md](docs/cli.md) | CLI quickstart and command reference |
+| [docs/benchmarks.md](docs/benchmarks.md) | Reproduce benchmark numbers and ablations |
+| [docs/release.md](docs/release.md) | Release workflow and versioning |
+| [docs/stages/](docs/stages/) | Research history for each mechanism |
+
+## Benchmarks
+
+Public retrieval/RAG-style benchmarks are useful regression tests, but they do not measure every Slowave feature. They mostly test fact recovery, not long-term accumulation, distillation, time-aware adaptation, or recall-driven memory reinforcement.
+
+| Benchmark | Cosine RAG | **Slowave** | Δ | Mem0 SOTA |
+|---|---:|---:|---:|---:|
+| LongMemEval (500q) | 60.0% | **70.0%** | +10pp | 94.4% |
+| LoCoMo (1986q) | 68.0% | **75.5%** | +7.5pp | 92.5% |
+
+Brain-only path: **$0/query · ~10ms recall · no API · data stays on device.**
+
+The gap to Mem0 is structurally about categories that reward LLM extraction/meta-cognition by construction, not just retrieval. See [docs/design.md](docs/design.md) and [docs/benchmarks.md](docs/benchmarks.md).
+
+## License
+
+MIT.

slowave-0.1.3/README.md

@@ -0,0 +1,130 @@
+# Slowave
+
+**Brain-inspired long-term memory for AI agents and desktop AI chats.** Slowave plugs into Claude Code, Cline, and Claude Desktop through MCP, giving them a shared memory that accumulates, consolidates, adapts, and recalls across sessions.
+
+Slowave's core thesis is simple: **language is not the memory system; language is one interface to it.** The memory engine works in latent space, the way brains appear to operate over distributed internal representations rather than over transcripts. Text is embedded once, then memory evolves through geometry, time, salience, replay, and activation. The default path uses **no LLM for ingest, consolidation, or recall**: inference is local, fast, CPU-friendly, private, and independent of any model provider.
+
+Critical features:
+
+- **No LLM in the core memory loop** — no API key, no cloud extraction step, no per-query model call.
+- **Local CPU inference** — BAAI/bge-small-en-v1.5 embeddings, SQLite, FAISS, and deterministic geometry.
+- **Brain-inspired consolidation** — raw events become episodes, episodes replay into prototypes, prototypes become latent schemas.
+- **Recall changes memory** — retrieved memories are reinforced; recall is an active operation, not a passive database lookup.
+- **Time-aware memory** — salience, decay, temporal anchors, supersession, and contradiction handling keep memory current.
+- **Generic ingestion** — not code-assistant-specific; it can remember coding work, planning, preferences, decisions, chat context, or any text interaction.
+- **Gated working memory** — `slowave_context` injects only a compact, cue-relevant memory brief instead of dumping history into the prompt.
+- **Provenance and inspection** — schemas trace back to episodes/raw events; the local dashboard exposes memory health and recall behavior.
+
+## What Slowave is for
+
+Slowave is a local long-term memory substrate for tools that otherwise forget between sessions. It is useful when you want an AI assistant to remember:
+
+- project conventions and architectural decisions;
+- personal preferences and communication style;
+- recurring workflows and commands;
+- previous debugging sessions and lessons learned;
+- open questions, warnings, constraints, and artifacts;
+- non-coding chat context from desktop AI conversations.
+
+It is intentionally not just a RAG layer. Existing memory systems usually retrieve stored text or ask an LLM to rewrite memories. Slowave treats memory as a living system: sessions create episodes, replay distills patterns, time changes salience, contradiction updates beliefs, and recall itself reinforces what was useful.
+
+## Install in minutes
+
+Slowave is a local memory service. Installing the package gives you two commands:
+
+- `slowave`: CLI, dashboard, manual recall/debugging.
+- `slowave-mcp`: MCP server used by Claude Desktop, Claude Code, and Cline.
+
+```bash
+brew tap mrsalty/slowave
+brew install slowave
+```
+
+PyPI publishing is not enabled yet, so `pip install slowave` / `pipx install slowave` will not work until the package is published to PyPI. If you are not using Homebrew, install from source:
+
+```bash
+git clone https://github.com/mrsalty/slowave
+cd slowave
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Verify:
+
+```bash
+which slowave-mcp
+slowave --help
+slowave-mcp --help
+slowave stats
+```
+
+Then choose your client and follow the short guide:
+
+| Client | Setup guide |
+|---|---|
+| Claude Desktop | [integrations/claude-desktop/](integrations/claude-desktop/) |
+| Claude Code | [integrations/claude-code/](integrations/claude-code/) |
+| Cline | [integrations/cline/](integrations/cline/) |
+
+**Important:** MCP setup alone is not enough. Every client needs:
+
+1. MCP configuration so the `slowave_*` tools are visible.
+2. Instruction/rules injection so the client actually calls Slowave during the task.
+3. A background worker for ongoing consolidation into distilled schemas.
+
+Episodes are created immediately when a session ends. The worker is what turns accumulated episodes into durable latent schemas for better future `slowave_context` injection.
+
+The integration guides contain the exact MCP JSON, prompt/rules block, worker setup, and verification command for each client. Start at [integrations/](integrations/) if you are unsure.
+
+Default storage: `~/.slowave/slowave.db`. No Ollama, OpenRouter, or other LLM backend is required for the default brain-only path.
+
+## Local dashboard
+
+Run a local 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, 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
+
+| | |
+|---|---|
+| [integrations/](integrations/) | Fast client-specific setup guides for Claude Desktop, Claude Code, and Cline |
+| [docs/install.md](docs/install.md) | Install, MCP setup, prompt/rules injection, verification |
+| [docs/agents.md](docs/agents.md) | MCP tool behavior and lifecycle for Claude Code, Cline, Claude Desktop |
+| [docs/agent-enforcement.md](docs/agent-enforcement.md) | Copy/paste prompt templates that make clients call Slowave consistently |
+| [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/dashboard.md](docs/dashboard.md) | Local dashboard guide |
+| [docs/cli.md](docs/cli.md) | CLI quickstart and command reference |
+| [docs/benchmarks.md](docs/benchmarks.md) | Reproduce benchmark numbers and ablations |
+| [docs/release.md](docs/release.md) | Release workflow and versioning |
+| [docs/stages/](docs/stages/) | Research history for each mechanism |
+
+## Benchmarks
+
+Public retrieval/RAG-style benchmarks are useful regression tests, but they do not measure every Slowave feature. They mostly test fact recovery, not long-term accumulation, distillation, time-aware adaptation, or recall-driven memory reinforcement.
+
+| Benchmark | Cosine RAG | **Slowave** | Δ | Mem0 SOTA |
+|---|---:|---:|---:|---:|
+| LongMemEval (500q) | 60.0% | **70.0%** | +10pp | 94.4% |
+| LoCoMo (1986q) | 68.0% | **75.5%** | +7.5pp | 92.5% |
+
+Brain-only path: **$0/query · ~10ms recall · no API · data stays on device.**
+
+The gap to Mem0 is structurally about categories that reward LLM extraction/meta-cognition by construction, not just retrieval. See [docs/design.md](docs/design.md) and [docs/benchmarks.md](docs/benchmarks.md).
+
+## License
+
+MIT.

slowave-0.1.3/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slowave"
+version = "0.1.3"
+description = "Brain-inspired long-term memory for AI agents — zero LLM during ingest or retrieval"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+readme = "README.md"
+authors = [{ name = "mrsalty" }]
+keywords = ["memory", "agent", "ai", "mcp", "neuroscience", "rag", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "numpy",
+  "torch",
+  "faiss-cpu",
+  "click>=8.1",
+  "sentence-transformers",
+  "mcp[cli]",
+]
+
+[project.urls]
+Homepage = "https://github.com/mrsalty/slowave"
+Repository = "https://github.com/mrsalty/slowave"
+Issues = "https://github.com/mrsalty/slowave/issues"
+Changelog = "https://github.com/mrsalty/slowave/releases"
+
+[project.optional-dependencies]
+dev = ["pytest", "black", "isort", "build", "twine"]
+
+[project.scripts]
+slowave = "slowave.cli.main:main"
+slowave-mcp = "slowave.mcp.server:main"
+
+[tool.setuptools.packages.find]
+include = ["slowave*"]
+exclude = ["tests*", "migrations*", "scripts*"]
+
+[tool.setuptools.package-data]
+slowave = ["storage/schema.sql", "llm/prompts/*.txt"]
+
+[tool.black]
+line-length = 100
+
+[tool.isort]
+profile = "black"
+line_length = 100

slowave-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

slowave-0.1.3/slowave/__init__.py

@@ -0,0 +1,10 @@
+"""Slowave: brain-inspired memory for AI agents.
+
+Public API entry points are in `slowave.core.engine.SlowaveEngine` and
+`slowave.core.config.SlowaveConfig`.
+"""
+from slowave.core.config import SlowaveConfig
+from slowave.core.engine import SlowaveEngine
+
+__all__ = ["SlowaveEngine", "SlowaveConfig"]
+__version__ = "0.1.3"

slowave-0.1.3/slowave/__main__.py

@@ -0,0 +1,13 @@
+"""`python -m slowave` dispatches to the Click CLI."""
+import os
+
+# macOS note: FAISS + PyTorch can sometimes load multiple OpenMP runtimes.
+# Pragmatic workaround to avoid a hard crash.
+os.environ.setdefault("KMP_DUPLICATE_LIB_OK", "TRUE")
+os.environ.setdefault("OMP_NUM_THREADS", "1")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+from slowave.cli.main import main
+
+if __name__ == "__main__":
+    main()