wavemind 2.1.0__tar.gz → 2.2.0__tar.gz

{wavemind-2.1.0 → wavemind-2.2.0}/CONTRIBUTING.md

@@ -92,6 +92,8 @@ Current scale roadmap:
 
 See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the full roadmap.
 See [`docs/RELEASE.md`](docs/RELEASE.md) for release mechanics.
+See [`docs/LAUNCH_KIT.md`](docs/LAUNCH_KIT.md) for public positioning,
+benchmark-claim guardrails, and community launch drafts.
 
 ## Pull Request Style
 

{wavemind-2.1.0 → wavemind-2.2.0}/MANIFEST.in

@@ -12,7 +12,13 @@ include requirements-optional.txt
 include docs/ROADMAP.md
 include docs/RELEASE.md
 include docs/PROJECT_BOARD.md
+include docs/DEMO_SCRIPT.md
+include docs/LAUNCH_KIT.md
+include docs/CHROMA_MIGRATION.md
+include docs/RU_LAUNCH_POSTS.md
+include docs/USE_CASES.md
 include docs/assets/benchmark-summary.svg
+include docs/assets/wavemind-social-card.svg
 include benchmarks/*.py
 include benchmarks/*.json
 include benchmarks/*.md

{wavemind-2.1.0 → wavemind-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.1.0
+Version: 2.2.0
 Summary: Local-first dynamic memory field with vector search and wave-field re-ranking
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaspianG/wavemind
@@ -52,25 +52,29 @@ Dynamic: license-file
 
 # WaveMind
 
-**A local-first dynamic memory field for software that needs to remember.**
+**Local-first dynamic memory for apps, agents, notebooks, and tools.**
 
-Most storage systems answer one question: "what record is closest to this
-query?" WaveMind adds a second question: "what information still matters right
-now?"
-
-It stores text, vectors, metadata, and recall state in SQLite. A wave-field
-priority layer then reinforces useful memories, lets stale facts fade, respects
-namespaces, and keeps the final recall set small enough for real applications.
+WaveMind stores memories in SQLite, finds relevant candidates with vector
+search, then uses a wave-field priority layer to decide what still matters:
+hot facts rise, stale facts fade, temporary facts expire, and namespaces keep
+users or projects isolated.
 
 ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
 [![PyPI](https://img.shields.io/pypi/v/wavemind.svg)](https://pypi.org/project/wavemind/)
 [![Tests](https://github.com/CaspianG/wavemind/actions/workflows/tests.yml/badge.svg)](https://github.com/CaspianG/wavemind/actions/workflows/tests.yml)
 ![License](https://img.shields.io/badge/license-MIT-green)
 
-[Concept](#concept) |
+<img src="https://raw.githubusercontent.com/CaspianG/wavemind/main/docs/assets/wavemind-social-card.svg" alt="WaveMind dynamic memory overview" width="820">
+
 [Quick Start](#quick-start) |
+[CLI](#cli-cheat-sheet) |
+[Studio](#wavemind-studio) |
+[Python Example](#python-example) |
+[HTTP Example](#http-example) |
+[Where Data Lives](#where-data-lives) |
 [LangChain](#langchain-memory) |
-[OpenClaw](#openclaw-integration) |
+[Chroma Migration](docs/CHROMA_MIGRATION.md) |
+[Use Cases](docs/USE_CASES.md) |
 [HTTP API](#http-api) |
 [Benchmarks](#benchmark) |
 [Roadmap](#roadmap) |
@@ -79,38 +83,246 @@ namespaces, and keeps the final recall set small enough for real applications.
 
 </div>
 
-## Concept
+## What Is WaveMind?
+
+WaveMind is a dynamic memory engine you can embed in a product.
 
-WaveMind is not a replacement for every database. It is a memory layer for
-information that changes in importance over time: preferences, decisions,
-corrections, notes, research snippets, support history, agent context, or any
-small-to-medium knowledge stream where "latest", "repeated", "expired", and
-"scoped to this user/project" matter.
+Use it when your app needs to remember things like user preferences, decisions,
+corrections, notes, research snippets, support history, agent context, or
+temporary facts.
 
-The simple version:
+The short version:
 
 ```text
-ordinary vector search:  find the nearest text
-WaveMind:                find the nearest useful memory
+normal vector search:  find the nearest text
+WaveMind:              find the nearest useful memory
 ```
 
-Under the hood, WaveMind still starts with normal vector search. The difference
-is the memory state around it: hotness, priority, decay, TTL, tags, namespaces,
-and optional memory-to-memory graph dynamics. That state is why the same stored
-fact can become stronger after repeated use, weaker after time passes, or
-disappear from recall after expiry.
+WaveMind is not trying to replace every vector database. It is the memory layer
+around retrieval: persistence, namespaces, TTL, hotness, priority, decay,
+explicit forgetting, audit events, and optional graph dynamics.
+
+## 60-Second Version
+
+| Question | Answer |
+|---|---|
+| What does it store? | Text memories, vectors, metadata, tags, TTL, priority, and recall state. |
+| Where does it store data? | A local SQLite file by default; Postgres is available for production state. |
+| How do I use it? | CLI, Python API, FastAPI HTTP server, LangChain memory, or framework adapters. |
+| What is different from Chroma/Qdrant? | WaveMind adds memory policy: hotness, decay, TTL, correction handling, and scoped recall. |
+| When should I not use it? | For huge static document search where a mature vector DB is already the right tool. |
+| What is the simplest install? | `python -m pip install wavemind` |
 
-## At a Glance
+## Why Use It?
 
 | If you need... | WaveMind gives you... |
 |---|---|
-| Memory that survives restarts | SQLite-backed `remember()`, `query()`, and `forget()`. |
-| Scoped recall per user, app, agent, or project | Namespaces and tags on every record. |
-| Information that changes importance over time | Hotness, priority, TTL, and decay-aware ranking. |
-| A local data source you can inspect and back up | One SQLite file is the source of truth. |
-| Easy integration | Python API, CLI, FastAPI server, and LangChain memory class. |
-| Honest benchmarks | Public LoCoMo, LongMemEval, BEIR/SciFact, and local policy checks. |
-| Production hooks | API keys, rate limits, audit log, Prometheus metrics, OpenTelemetry traces, backups, and optional external indexes. |
+| Memory that survives restarts | One SQLite file stores text, vectors, metadata, TTL, and recall state. |
+| Per-user or per-project recall | Namespaces and tags keep memories separated. |
+| Temporary facts | `ttl_seconds` lets facts expire automatically. |
+| Corrections and changing preferences | Newer or reinforced memories can outrank stale ones. |
+| A simple integration path | Python API, CLI, FastAPI server, and LangChain memory class. |
+| Production hygiene | Backups, audit log, API keys, rate limits, Prometheus metrics, and OpenTelemetry traces. |
+
+## Quick Start
+
+The shortest path from install to first recall:
+
+```sh
+python -m pip install wavemind
+wavemind remember "Andrey is a trader" --namespace demo
+wavemind query "What does Andrey do?" --namespace demo
+```
+
+Need a reminder after install?
+
+```sh
+wavemind quickstart
+```
+
+Want to see and manage memory in a browser?
+
+```sh
+wavemind studio
+```
+
+By default, WaveMind creates `wavemind.sqlite3` in the current working
+directory. That file is the local source of truth. Keep it out of git and back
+it up like application state.
+
+## CLI Cheat Sheet
+
+Start here if you only want to use WaveMind from the terminal:
+
+| Goal | Command |
+|---|---|
+| Show first-run help | `wavemind quickstart` |
+| Store a memory | `wavemind remember "Andrey prefers short answers" --namespace user:42` |
+| Search memory | `wavemind query "answer style" --namespace user:42` |
+| Open local dashboard | `wavemind studio` |
+| See stored state | `wavemind stats --namespace user:42` |
+| Delete a namespace | `wavemind forget --namespace user:42` |
+| Import notes | `wavemind import ./notes.txt --namespace project:alpha` |
+| Use another database file | `wavemind --db ./state/memory.sqlite3 query "budget" --namespace user:42` |
+| Start the HTTP API | `wavemind --db ./state/memory.sqlite3 serve --host 127.0.0.1 --port 8000` |
+
+After this point, choose the integration path you need: Python, HTTP, LangChain,
+framework adapters, benchmarks, or production deployment.
+
+## WaveMind Studio
+
+WaveMind Studio is the built-in local dashboard. It runs on top of the same
+FastAPI app and SQLite database as the CLI:
+
+```sh
+wavemind studio
+```
+
+It opens `http://127.0.0.1:8000/studio` and gives you:
+
+| View | What it is for |
+|---|---|
+| Memory map | See field energy as a heatmap. |
+| Namespace explorer | Inspect memories per user, project, agent, or tenant. |
+| Live query tester | Test recall before wiring it into an app. |
+| Feedback buttons | Mark recalled memories as useful or not useful. |
+| Import/export | Import local files and export a namespace snapshot. |
+| Backup | Create SQLite backups from the browser. |
+| Conflict visualizer | Inspect correction groups when memories disagree. |
+
+For a server-safe local bind:
+
+```sh
+wavemind --db ./state/wavemind.sqlite3 studio --host 127.0.0.1 --port 8000
+```
+
+## Python Example
+
+```python
+from wavemind import WaveMind
+
+memory = WaveMind(db_path="./state/wavemind.sqlite3")
+
+memory.remember(
+    "The user prefers short practical answers.",
+    namespace="user:42",
+    tags=["preference"],
+)
+
+hits = memory.query("How should I answer this user?", namespace="user:42", top_k=3)
+for hit in hits:
+    print(hit.score, hit.text)
+```
+
+The integration pattern is intentionally small:
+
+1. Call `query()` before your app, agent, tool, or UI needs context.
+2. Pass the returned memories into your prompt, screen, search result, or
+   decision function.
+3. Call `remember()` after something worth keeping happens.
+
+## HTTP Example
+
+The FastAPI server is included in the base install:
+
+```sh
+wavemind --db ./state/wavemind.sqlite3 serve --host 127.0.0.1 --port 8000
+```
+
+Then use WaveMind from any language:
+
+```sh
+curl -X POST http://127.0.0.1:8000/remember \
+  -H "Content-Type: application/json" \
+  -d "{\"text\":\"Andrey prefers short answers\",\"namespace\":\"user:42\",\"tags\":[\"preference\"]}"
+
+curl -X POST http://127.0.0.1:8000/query \
+  -H "Content-Type: application/json" \
+  -d "{\"query\":\"How should I answer?\",\"namespace\":\"user:42\",\"top_k\":3}"
+```
+
+## Where Data Lives
+
+WaveMind is local-first. The SQLite database stores memories, vectors, metadata,
+namespaces, tags, TTL, hotness, priority, and audit events.
+
+| runtime | Suggested database path |
+|---|---|
+| quick CLI experiment | `./wavemind.sqlite3` |
+| Python app or agent | `./state/wavemind.sqlite3` |
+| desktop app | user data directory, for example `%APPDATA%` or `~/.local/share` |
+| server daemon | `/var/lib/wavemind/wavemind.sqlite3` |
+| Docker | mounted volume, for example `/data/wavemind.sqlite3` |
+
+Explicit path:
+
+```sh
+wavemind --db ./state/app_memory.sqlite3 remember "Andrey prefers short answers" --namespace user:42
+wavemind --db ./state/app_memory.sqlite3 query "answer style" --namespace user:42
+```
+
+## Common Ways To Use It
+
+| You are building... | Start with... |
+|---|---|
+| Python app | `from wavemind import WaveMind` |
+| LangChain agent | `WaveMindMemory` from `wavemind.integrations.langchain` |
+| LangGraph workflow | `make_recall_node()` and `make_persist_node()` |
+| LlamaIndex pipeline | `WaveMindRetriever` |
+| CrewAI or AutoGen loop | The adapters in `wavemind.integrations` |
+| Node, Go, Ruby, PHP, or no-code app | `wavemind serve` and the HTTP API |
+| Personal knowledge base | Store notes by project namespace and query locally |
+| Support or CRM workflow | Store customer issues, resolutions, preferences, and corrections |
+| Research or trading notebook | Store observations with source metadata and TTL for temporary hypotheses |
+
+For migrations from existing local vector memory, start with
+[`docs/CHROMA_MIGRATION.md`](docs/CHROMA_MIGRATION.md).
+
+## Minimal Agent Loop
+
+```python
+from wavemind import WaveMind
+
+memory = WaveMind(db_path="./state/agent.sqlite3")
+
+def run_turn(user_id: str, user_text: str) -> str:
+    namespace = f"user:{user_id}"
+    hits = memory.query(user_text, namespace=namespace, top_k=5, min_score=0.25)
+    recalled = "\n".join(f"- {hit.text}" for hit in hits)
+
+    answer = call_your_llm(f"Relevant memory:\n{recalled}\n\nUser: {user_text}")
+
+    memory.remember(f"User said: {user_text}", namespace=namespace, tags=["conversation"])
+    memory.remember(f"Assistant answered: {answer}", namespace=namespace, tags=["conversation"])
+    return answer
+```
+
+## Terminal Demo
+
+From a cloned repository:
+
+```text
+$ python examples/demo.py
+[ok] Remembered: "Andrey is a trader who tracks market breakouts."
+[ok] Remembered: "Andrey prefers short practical answers about product decisions."
+
+Query: "Andrey trader preferences"
+-> Result 1 (0.60): "Andrey is a trader who tracks market breakouts."
+-> Result 2 (0.30): "Andrey prefers short practical answers about product decisions."
+```
+
+The demo is offline, keyless, and uses the built-in hash encoder.
+
+To see the behavior that plain vector search does not provide:
+
+```sh
+python examples/dynamic_memory_demo.py
+```
+
+That demo shows corrected facts outranking stale facts, temporary memory
+expiring, namespace isolation, and index-health reporting.
+
+## How The Memory Field Works
 
 ```mermaid
 flowchart LR
@@ -125,10 +337,9 @@ flowchart LR
     F --> D
 ```
 
-## What The Wave Field Does
-
-The "field" is the dynamic layer around stored memories. It is not just a
-marketing name for embeddings.
+The wave field is the dynamic layer around stored memories. It is not a
+replacement for embeddings; it is the policy that decides which candidate
+memories should still matter.
 
 | signal | Plain meaning | Effect |
 |---|---|---|
@@ -145,39 +356,6 @@ memories, not a continuous mathematical physics field. That honesty matters:
 WaveMind is useful today as a dynamic memory engine, while the research path is
 to make the field dynamics more explicit, measurable, and scalable.
 
-## Terminal Demo
-
-From a cloned repository:
-
-```text
-$ python examples/demo.py
-[ok] Remembered: "Andrey is a trader who tracks market breakouts."
-[ok] Remembered: "Andrey prefers short practical answers about product decisions."
-
-Query: "Andrey trader preferences"
--> Result 1 (0.60): "Andrey is a trader who tracks market breakouts."
--> Result 2 (0.30): "Andrey prefers short practical answers about product decisions."
-```
-
-The demo is offline, keyless, and uses the built-in hash encoder.
-
-## Quick Start
-
-Install from PyPI and create your first local memory:
-
-```sh
-python -m pip install wavemind
-wavemind remember "Andrey is a trader" --namespace demo
-wavemind query "trader" --namespace demo
-```
-
-What happens here:
-
-- `remember` writes the text and its vector pattern into a local SQLite database.
-- By default, the database file is `wavemind.sqlite3` in your current working directory.
-- `--namespace demo` keeps this memory separate from other users, agents, or projects.
-- `query` reads from the same SQLite file and returns the closest remembered texts.
-
 ## Optional Embeddings
 
 For sentence-transformer embeddings:
@@ -215,6 +393,16 @@ wavemind --index faiss-persisted query "trader" --namespace demo
 SQLite or Postgres remains the source of truth. The persisted FAISS files are a
 candidate-index snapshot and are validated against the current memory ids on
 load. If the snapshot does not match the stored memories, WaveMind rebuilds it.
+You can also check and rebuild the candidate index explicitly:
+
+```sh
+wavemind --index faiss-persisted index-health --json
+wavemind --index faiss-persisted rebuild-index
+```
+
+Index health compares durable memory ids against the candidate index. Local
+indexes report exact missing/extra ids; service backends report exact ids when
+the backend exposes an id scan and otherwise fall back to count-based health.
 
 pgvector setup:
 
@@ -250,38 +438,6 @@ production latency and durability should be measured against a real Qdrant
 service. If `WAVEMIND_QDRANT_URL` is missing, WaveMind raises a clear error
 instead of silently falling back to another backend.
 
-## Data Location
-
-For an explicit database path, put global options before the command:
-
-```sh
-wavemind --db ./app_memory.sqlite3 remember "Andrey is a trader" --namespace demo
-wavemind --db ./app_memory.sqlite3 query "trader" --namespace demo
-```
-
-WaveMind is local-first. One SQLite file is the source of truth for texts,
-metadata, vectors, namespaces, tags, TTL, and recall state. For real agents,
-prefer an explicit path under your application's state directory:
-
-```python
-from wavemind import WaveMind
-
-memory = WaveMind(db_path="./state/wavemind.sqlite3")
-memory.remember("The user prefers short answers.", namespace="user:42", tags=["preference"])
-```
-
-Useful storage patterns:
-
-| runtime | Suggested database path |
-|---|---|
-| local CLI experiment | `./wavemind.sqlite3` |
-| Python app or agent | `./state/wavemind.sqlite3` |
-| OpenClaw sidecar | `~/.openclaw/wavemind/<agent-id>.sqlite3` |
-| server daemon | `/var/lib/wavemind/wavemind.sqlite3` |
-| Docker | mounted volume, for example `/data/wavemind.sqlite3` |
-
-Keep the SQLite file out of git. Back it up like any other application state.
-
 ## Storage Backends
 
 SQLite is the default source of truth. For multi-tenant production deployments,
@@ -355,6 +511,8 @@ curl http://127.0.0.1:8000/stats?namespace=demo
 curl http://127.0.0.1:8000/audit?namespace=demo
 curl http://127.0.0.1:8000/metrics
 curl http://127.0.0.1:8000/observability
+curl http://127.0.0.1:8000/index/health
+curl -X POST http://127.0.0.1:8000/index/rebuild
 curl -X POST http://127.0.0.1:8000/backup -H "Content-Type: application/json" -d '{"path":"./backups","keep_last":7}'
 ```
 
@@ -362,6 +520,9 @@ curl -X POST http://127.0.0.1:8000/backup -H "Content-Type: application/json" -d
 `purge_expired`. Query audit is opt-in with `WAVEMIND_AUDIT_QUERIES=1` because
 writing an audit row for every query changes latency. `/metrics` returns a
 Prometheus-compatible text payload without adding a required dependency.
+`/index/health` reports source-of-truth versus candidate-index consistency.
+`/index/rebuild` rebuilds the candidate index from stored active memories and
+logs an `index_rebuild` audit event.
 
 OpenTelemetry traces are optional and off by default:
 
@@ -392,9 +553,9 @@ Role behavior:
 
 | role | Env var | Allows |
 |---|---|---|
-| read | `WAVEMIND_READ_KEYS` | `/query`, `/stats`, `/metrics` |
+| read | `WAVEMIND_READ_KEYS` | `/query`, `/stats`, `/metrics`, `/index/health` |
 | write | `WAVEMIND_WRITE_KEYS` | read actions plus `/remember` and `/import` |
-| admin | `WAVEMIND_ADMIN_KEYS` or `WAVEMIND_API_KEYS` | all actions, including `/audit`, `/backup`, and `/forget` |
+| admin | `WAVEMIND_ADMIN_KEYS` or `WAVEMIND_API_KEYS` | all actions, including `/audit`, `/backup`, `/index/rebuild`, and `/forget` |
 
 Keys are accepted through `Authorization: Bearer <key>` or `X-API-Key: <key>`.
 If no key env vars are set, authentication is disabled for local development.
@@ -442,7 +603,7 @@ Offline runnable example from a cloned repository:
 python examples/langchain_memory.py
 ```
 
-## Integration Patterns
+## Framework Integrations
 
 WaveMind only needs two touch points in an agent, service, notebook, or app:
 
@@ -471,6 +632,9 @@ That makes it usable in more than LangChain:
 | Preference/profile memory | Store with tags such as `profile`, `preference`, `project`, `decision`. |
 | Corrections/privacy | Use `forget()` or namespace deletion workflows. |
 
+More examples: [`docs/USE_CASES.md`](docs/USE_CASES.md).
+Migrating from a Chroma memory store: [`docs/CHROMA_MIGRATION.md`](docs/CHROMA_MIGRATION.md).
+
 Framework examples in this repository:
 
 | Framework / pattern | Example |
@@ -483,26 +647,6 @@ Framework examples in this repository:
 | AutoGen-style hooks | `wavemind.integrations.autogen`, `examples/framework_integrations.py` |
 | Namespace sharding | `examples/sharded_memory.py` |
 
-Minimal custom agent loop:
-
-```python
-from wavemind import WaveMind
-
-memory = WaveMind(db_path="./state/wavemind.sqlite3")
-
-def run_turn(user_id: str, user_text: str, history: list[str]) -> str:
-    namespace = f"user:{user_id}"
-    hits = memory.query(user_text, namespace=namespace, top_k=5, min_score=0.25)
-    recalled = "\n".join(f"- {hit.text}" for hit in hits)
-
-    prompt = f"Relevant memory:\n{recalled}\n\nUser: {user_text}"
-    answer = call_your_llm(prompt, history)
-
-    memory.remember(f"User said: {user_text}", namespace=namespace, tags=["conversation"])
-    memory.remember(f"Assistant answered: {answer}", namespace=namespace, tags=["conversation"])
-    return answer
-```
-
 ## OpenClaw Integration
 
 [OpenClaw memory](https://docs.openclaw.ai/concepts/memory) is file-centered:
@@ -1071,6 +1215,9 @@ python benchmarks/dynamic_memory_benchmark.py --engines wavemind chroma --memori
 
 WaveMind is not trying to replace dedicated vector databases at scale. The intended product gap is dynamic priority: frequently used memories can become hotter while old or low-priority memories fade. For static RAG over large document collections, use a mature vector database. For memory that needs persistence, scoped recall, TTL, forgetting, and reinforcement, WaveMind is designed to sit above or beside the vector index.
 
+If you already use Chroma for local memory, see the practical migration guide:
+[`docs/CHROMA_MIGRATION.md`](docs/CHROMA_MIGRATION.md).
+
 ## Known Limitations
 
 - Optimal capacity on the current NumPy exact index is up to 1000 records.
@@ -1107,6 +1254,7 @@ WaveMind is not trying to replace dedicated vector databases at scale. The inten
 ## Roadmap
 
 Full roadmap: [`docs/ROADMAP.md`](docs/ROADMAP.md).
+Launch and positioning kit: [`docs/LAUNCH_KIT.md`](docs/LAUNCH_KIT.md).
 
 Near-term priorities: