wavemind 2.0.1__tar.gz → 2.0.3__tar.gz

{wavemind-2.0.1/wavemind.egg-info → wavemind-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.0.1
+Version: 2.0.3
 Summary: Persistent dynamic memory engine with vector search and wave-field re-ranking
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaspianG/wavemind
@@ -27,6 +27,7 @@ Requires-Dist: langchain-classic>=1.0; extra == "langchain"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: langchain-classic>=1.0; extra == "dev"
 Dynamic: license-file
 
 # WaveMind is persistent dynamic memory for AI agents: vector search first, wave-field priority second, SQLite as the source of truth.
@@ -37,6 +38,8 @@ Dynamic: license-file
 
 ## Terminal Demo
 
+From a cloned repository:
+
 ```text
 $ python examples/demo.py
 ✓ Remembered: "Andrey is a trader who tracks market breakouts."
@@ -51,23 +54,66 @@ 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 -e .
+python -m pip install wavemind
 wavemind remember "Andrey is a trader" --namespace demo
 wavemind query "trader" --namespace demo
 ```
 
-This creates `wavemind.sqlite3` in your current working directory.
+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:
 
 ```sh
-python -m pip install -e ".[sentence]"
+python -m pip install "wavemind[sentence]"
 wavemind --encoder sentence remember "Andrey is a trader" --namespace demo
 wavemind --encoder sentence query "What does Andrey do?" --namespace demo
 ```
 
-One-file setup scripts are also included:
+## Data Location
+
+For an explicit database path, put global options before the command:
+
+```sh
+wavemind --db ./agent_memory.sqlite3 remember "Andrey is a trader" --namespace demo
+wavemind --db ./agent_memory.sqlite3 query "trader" --namespace demo
+```
+
+## HTTP API
+
+Run the local FastAPI server:
+
+```sh
+wavemind --db ./agent_memory.sqlite3 serve --host 127.0.0.1 --port 8000
+```
+
+Store and query memory over HTTP:
+
+```sh
+curl -X POST http://127.0.0.1:8000/remember -H "Content-Type: application/json" -d "{\"text\":\"Andrey is a trader\",\"namespace\":\"demo\"}"
+curl -X POST http://127.0.0.1:8000/query -H "Content-Type: application/json" -d "{\"query\":\"trader\",\"namespace\":\"demo\",\"top_k\":1}"
+```
+
+## Install From Source
+
+For contributors installing from a local clone:
+
+```sh
+git clone https://github.com/CaspianG/wavemind.git
+cd wavemind
+python -m pip install -e ".[sentence]"
+```
+
+One-file setup scripts are also included in the repository:
 
 ```sh
 sh install.sh
@@ -94,12 +140,41 @@ memory = WaveMindMemory(db_path="agent_memory.sqlite3")
 # Replace: memory = ConversationBufferMemory()
 ```
 
-Offline runnable example:
+Offline runnable example from a cloned repository:
 
 ```sh
 python examples/langchain_memory.py
 ```
 
+## Why Dynamic Memory
+
+WaveMind is not positioned as "a faster Chroma." Chroma, Qdrant, Pinecone, and Weaviate are vector databases: they store embeddings and return nearest neighbors. That is the right tool for many static RAG workloads.
+
+WaveMind is an agent memory layer. It still uses vector search first, but then applies memory-specific signals that a plain vector store does not model by default:
+
+| memory behavior | Why it matters for agents | WaveMind mechanism |
+|---|---|---|
+| Hot memories | Facts recalled repeatedly should become easier to recall again. | Wave-field hotness and priority updates. |
+| Aging memories | Old low-value facts should fade instead of competing forever. | TTL and decay-aware scoring. |
+| Scoped memory | One user, agent, workspace, or project should not leak into another. | Namespaces and tags. |
+| Explicit forgetting | Agents need deletion, privacy cleanup, and correction workflows. | `forget()` plus SQLite persistence. |
+| Stable restart behavior | A memory system must survive process restarts. | SQLite source of truth, reloadable indexes. |
+| Vector plus memory rank | Semantic similarity is necessary but not sufficient for long-running agents. | k-NN candidates first, wave field as re-ranker. |
+
+The current Chroma benchmark below is intentionally conservative: it compares static retrieval on the same facts and the same hash embeddings. That benchmark is useful, but it does not exercise WaveMind's main product thesis: memory that changes over time as an agent recalls, reinforces, ages, and forgets information.
+
+The benchmark that should decide whether WaveMind is worth using is a dynamic agent-memory benchmark:
+
+| scenario | What should happen |
+|---|---|
+| A user repeats a preference many times. | WaveMind should rank it higher than equally similar but unused facts. |
+| A fact expires via TTL. | WaveMind should suppress it without requiring manual vector cleanup. |
+| A user corrects an old fact. | WaveMind should prefer the newer or reinforced memory. |
+| A query is ambiguous across namespaces. | WaveMind should return only the scoped user's memory. |
+| A long conversation has many irrelevant facts. | WaveMind should preserve useful recall instead of treating all vectors equally. |
+
+In short: static vector search answers "what is nearest?" Agent memory also asks "what is still relevant, reinforced, scoped, and allowed to be remembered?"
+
 ## Benchmark
 
 Real Russian sentences from Tatoeba, 50 one-word queries, NumPy exact index.
@@ -118,7 +193,7 @@ Capacity check with the hash encoder:
 | 1000 | 0.88 | 1.00 | 1.50 ms |
 | 5000 | 0.72 | 0.88 | 5.68 ms |
 
-Run locally:
+Run locally from a cloned repository:
 
 ```sh
 python benchmarks/ru_sentences_benchmark.py --sentences 200 --queries 50 --encoder hash --index numpy
@@ -130,12 +205,14 @@ Agent-memory benchmark against Chroma:
 200 Russian user facts, 50 natural-language questions, same precomputed `HashingTextEncoder` embeddings for WaveMind and Chroma.
 Full machine-readable result: `benchmarks/agent_memory_results.json`.
 
+This is a static retrieval benchmark. It measures baseline ranking and latency, not hotness, TTL, repeated recall, or memory aging.
+
 | engine | precision@1 | precision@3 | avg latency |
 |---|---:|---:|---:|
 | WaveMind | 0.82 | 0.90 | 2.25 ms |
 | Chroma | 0.82 | 0.88 | 0.93 ms |
 
-Run locally:
+Run locally from a cloned repository:
 
 ```sh
 pip install -e ".[bench]"
@@ -154,7 +231,7 @@ python benchmarks/agent_memory_benchmark.py --engines wavemind chroma --facts 20
 | Best fit | Small to medium agent memory with dynamic recall | Local RAG apps and prototypes | Large-scale vector search |
 | Scale target today | Up to 1000 optimal on NumPy, FAISS recommended beyond 5000 | Larger than WaveMind local mode | Production scale |
 
-WaveMind is not trying to replace dedicated vector databases at scale. Its difference is dynamic priority: frequently used memories can become hotter while old or low-priority memories fade.
+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 agent memory that needs persistence, scoped recall, TTL, forgetting, and reinforcement, WaveMind is designed to sit above or beside the vector index.
 
 ## Known Limitations
 
@@ -164,10 +241,12 @@ WaveMind is not trying to replace dedicated vector databases at scale. Its diffe
 - `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` requires about 420 MB of model files and measured about 53 ms per query on the benchmark machine.
 - The Chroma comparison currently uses shared precomputed hash embeddings to isolate retrieval/ranking behavior; semantic model comparisons should be run separately.
 - In the 200-fact agent benchmark, Chroma is faster on average while WaveMind is slightly higher at `precision@3`.
+- The current public benchmark does not yet prove the dynamic-memory advantage. The next benchmark must test hotness, TTL, corrections, namespace isolation, and repeated recall.
 
 ## Roadmap
 
 - FAISS-first production index path with persisted index rebuilds.
+- Dynamic agent-memory benchmark against Chroma/Qdrant: hotness, TTL, stale-fact suppression, corrections, and namespace isolation.
 - Expand the agent-memory benchmark to sentence-transformers, FAISS, Chroma default embeddings, and Qdrant.
 - Better semantic query expansion for short and ambiguous queries.
 - Namespace quotas, backups, and daemon hardening for SaaS use.

{wavemind-2.0.1 → wavemind-2.0.3}/README.md

@@ -6,6 +6,8 @@
 
 ## Terminal Demo
 
+From a cloned repository:
+
 ```text
 $ python examples/demo.py
 ✓ Remembered: "Andrey is a trader who tracks market breakouts."
@@ -20,23 +22,66 @@ 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 -e .
+python -m pip install wavemind
 wavemind remember "Andrey is a trader" --namespace demo
 wavemind query "trader" --namespace demo
 ```
 
-This creates `wavemind.sqlite3` in your current working directory.
+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:
 
 ```sh
-python -m pip install -e ".[sentence]"
+python -m pip install "wavemind[sentence]"
 wavemind --encoder sentence remember "Andrey is a trader" --namespace demo
 wavemind --encoder sentence query "What does Andrey do?" --namespace demo
 ```
 
-One-file setup scripts are also included:
+## Data Location
+
+For an explicit database path, put global options before the command:
+
+```sh
+wavemind --db ./agent_memory.sqlite3 remember "Andrey is a trader" --namespace demo
+wavemind --db ./agent_memory.sqlite3 query "trader" --namespace demo
+```
+
+## HTTP API
+
+Run the local FastAPI server:
+
+```sh
+wavemind --db ./agent_memory.sqlite3 serve --host 127.0.0.1 --port 8000
+```
+
+Store and query memory over HTTP:
+
+```sh
+curl -X POST http://127.0.0.1:8000/remember -H "Content-Type: application/json" -d "{\"text\":\"Andrey is a trader\",\"namespace\":\"demo\"}"
+curl -X POST http://127.0.0.1:8000/query -H "Content-Type: application/json" -d "{\"query\":\"trader\",\"namespace\":\"demo\",\"top_k\":1}"
+```
+
+## Install From Source
+
+For contributors installing from a local clone:
+
+```sh
+git clone https://github.com/CaspianG/wavemind.git
+cd wavemind
+python -m pip install -e ".[sentence]"
+```
+
+One-file setup scripts are also included in the repository:
 
 ```sh
 sh install.sh
@@ -63,12 +108,41 @@ memory = WaveMindMemory(db_path="agent_memory.sqlite3")
 # Replace: memory = ConversationBufferMemory()
 ```
 
-Offline runnable example:
+Offline runnable example from a cloned repository:
 
 ```sh
 python examples/langchain_memory.py
 ```
 
+## Why Dynamic Memory
+
+WaveMind is not positioned as "a faster Chroma." Chroma, Qdrant, Pinecone, and Weaviate are vector databases: they store embeddings and return nearest neighbors. That is the right tool for many static RAG workloads.
+
+WaveMind is an agent memory layer. It still uses vector search first, but then applies memory-specific signals that a plain vector store does not model by default:
+
+| memory behavior | Why it matters for agents | WaveMind mechanism |
+|---|---|---|
+| Hot memories | Facts recalled repeatedly should become easier to recall again. | Wave-field hotness and priority updates. |
+| Aging memories | Old low-value facts should fade instead of competing forever. | TTL and decay-aware scoring. |
+| Scoped memory | One user, agent, workspace, or project should not leak into another. | Namespaces and tags. |
+| Explicit forgetting | Agents need deletion, privacy cleanup, and correction workflows. | `forget()` plus SQLite persistence. |
+| Stable restart behavior | A memory system must survive process restarts. | SQLite source of truth, reloadable indexes. |
+| Vector plus memory rank | Semantic similarity is necessary but not sufficient for long-running agents. | k-NN candidates first, wave field as re-ranker. |
+
+The current Chroma benchmark below is intentionally conservative: it compares static retrieval on the same facts and the same hash embeddings. That benchmark is useful, but it does not exercise WaveMind's main product thesis: memory that changes over time as an agent recalls, reinforces, ages, and forgets information.
+
+The benchmark that should decide whether WaveMind is worth using is a dynamic agent-memory benchmark:
+
+| scenario | What should happen |
+|---|---|
+| A user repeats a preference many times. | WaveMind should rank it higher than equally similar but unused facts. |
+| A fact expires via TTL. | WaveMind should suppress it without requiring manual vector cleanup. |
+| A user corrects an old fact. | WaveMind should prefer the newer or reinforced memory. |
+| A query is ambiguous across namespaces. | WaveMind should return only the scoped user's memory. |
+| A long conversation has many irrelevant facts. | WaveMind should preserve useful recall instead of treating all vectors equally. |
+
+In short: static vector search answers "what is nearest?" Agent memory also asks "what is still relevant, reinforced, scoped, and allowed to be remembered?"
+
 ## Benchmark
 
 Real Russian sentences from Tatoeba, 50 one-word queries, NumPy exact index.
@@ -87,7 +161,7 @@ Capacity check with the hash encoder:
 | 1000 | 0.88 | 1.00 | 1.50 ms |
 | 5000 | 0.72 | 0.88 | 5.68 ms |
 
-Run locally:
+Run locally from a cloned repository:
 
 ```sh
 python benchmarks/ru_sentences_benchmark.py --sentences 200 --queries 50 --encoder hash --index numpy
@@ -99,12 +173,14 @@ Agent-memory benchmark against Chroma:
 200 Russian user facts, 50 natural-language questions, same precomputed `HashingTextEncoder` embeddings for WaveMind and Chroma.
 Full machine-readable result: `benchmarks/agent_memory_results.json`.
 
+This is a static retrieval benchmark. It measures baseline ranking and latency, not hotness, TTL, repeated recall, or memory aging.
+
 | engine | precision@1 | precision@3 | avg latency |
 |---|---:|---:|---:|
 | WaveMind | 0.82 | 0.90 | 2.25 ms |
 | Chroma | 0.82 | 0.88 | 0.93 ms |
 
-Run locally:
+Run locally from a cloned repository:
 
 ```sh
 pip install -e ".[bench]"
@@ -123,7 +199,7 @@ python benchmarks/agent_memory_benchmark.py --engines wavemind chroma --facts 20
 | Best fit | Small to medium agent memory with dynamic recall | Local RAG apps and prototypes | Large-scale vector search |
 | Scale target today | Up to 1000 optimal on NumPy, FAISS recommended beyond 5000 | Larger than WaveMind local mode | Production scale |
 
-WaveMind is not trying to replace dedicated vector databases at scale. Its difference is dynamic priority: frequently used memories can become hotter while old or low-priority memories fade.
+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 agent memory that needs persistence, scoped recall, TTL, forgetting, and reinforcement, WaveMind is designed to sit above or beside the vector index.
 
 ## Known Limitations
 
@@ -133,10 +209,12 @@ WaveMind is not trying to replace dedicated vector databases at scale. Its diffe
 - `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` requires about 420 MB of model files and measured about 53 ms per query on the benchmark machine.
 - The Chroma comparison currently uses shared precomputed hash embeddings to isolate retrieval/ranking behavior; semantic model comparisons should be run separately.
 - In the 200-fact agent benchmark, Chroma is faster on average while WaveMind is slightly higher at `precision@3`.
+- The current public benchmark does not yet prove the dynamic-memory advantage. The next benchmark must test hotness, TTL, corrections, namespace isolation, and repeated recall.
 
 ## Roadmap
 
 - FAISS-first production index path with persisted index rebuilds.
+- Dynamic agent-memory benchmark against Chroma/Qdrant: hotness, TTL, stale-fact suppression, corrections, and namespace isolation.
 - Expand the agent-memory benchmark to sentence-transformers, FAISS, Chroma default embeddings, and Qdrant.
 - Better semantic query expansion for short and ambiguous queries.
 - Namespace quotas, backups, and daemon hardening for SaaS use.

{wavemind-2.0.1 → wavemind-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wavemind"
-version = "2.0.1"
+version = "2.0.3"
 description = "Persistent dynamic memory engine with vector search and wave-field re-ranking"
 readme = "README.md"
 license = "MIT"
@@ -37,6 +37,7 @@ langchain = [
 dev = [
   "pytest>=8",
   "httpx>=0.27",
+  "langchain-classic>=1.0",
 ]
 
 [project.scripts]

{wavemind-2.0.1 → wavemind-2.0.3}/tests/test_api.py

@@ -1,6 +1,6 @@
 from fastapi.testclient import TestClient
 
-from wavemind import HashingTextEncoder, WaveMind
+from wavemind import HashingTextEncoder, WaveMind, __version__
 from wavemind.api import create_app
 
 
@@ -50,3 +50,42 @@ def test_fastapi_remember_query_forget_and_stats(tmp_path):
     empty = client.post("/query", json={"text": "кошка", "namespace": "pets"})
     assert empty.json()["results"] == []
 
+
+def test_fastapi_query_accepts_query_alias(tmp_path):
+    mind = WaveMind(
+        db_path=tmp_path / "api.sqlite3",
+        width=32,
+        height=32,
+        layers=2,
+        encoder=HashingTextEncoder(vector_dim=64),
+        score_threshold=0.0,
+    )
+    client = TestClient(create_app(mind=mind))
+
+    remember = client.post(
+        "/remember",
+        json={"text": "Andrey is a trader", "namespace": "demo"},
+    )
+    assert remember.status_code == 200
+
+    query = client.post(
+        "/query",
+        json={"query": "trader", "namespace": "demo", "top_k": 1},
+    )
+
+    assert query.status_code == 200
+    assert query.json()["results"][0]["text"] == "Andrey is a trader"
+
+
+def test_fastapi_version_matches_package_version():
+    app = create_app(
+        mind=WaveMind(
+            db_path=None,
+            width=16,
+            height=16,
+            layers=1,
+            encoder=HashingTextEncoder(vector_dim=16),
+        )
+    )
+
+    assert app.version == __version__

{wavemind-2.0.1 → wavemind-2.0.3}/tests/test_packaging_files.py

@@ -1,4 +1,13 @@
 from pathlib import Path
+import tomllib
+
+import wavemind
+
+
+def test_package_version_matches_pyproject():
+    pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
+
+    assert wavemind.__version__ == pyproject["project"]["version"]
 
 
 def test_sentence_extra_is_available_for_install_scripts():
@@ -22,6 +31,18 @@ def test_langchain_extra_installs_classic_memory_api():
     assert '"langchain-classic>=1.0"' in pyproject
 
 
+def test_dev_extra_runs_against_real_langchain_memory_api():
+    pyproject = Path("pyproject.toml").read_text(encoding="utf-8")
+    integration = Path("wavemind/integrations/langchain.py").read_text(
+        encoding="utf-8"
+    )
+
+    assert "dev = [" in pyproject
+    assert '"langchain-classic>=1.0"' in pyproject
+    assert "class BaseMemory" not in integration
+    assert 'pip install "wavemind[langchain]"' in integration
+
+
 def test_install_scripts_create_venv_and_install_sentence_extra():
     install_sh = Path("install.sh").read_text(encoding="utf-8")
     install_bat = Path("install.bat").read_text(encoding="utf-8")

{wavemind-2.0.1 → wavemind-2.0.3}/wavemind/__init__.py

@@ -8,6 +8,8 @@ from .encoders import (
 )
 from .storage import MemoryRecord, SQLiteMemoryStore
 
+__version__ = "2.0.3"
+
 __all__ = [
     "FieldProjector",
     "HashingTextEncoder",
@@ -18,5 +20,6 @@ __all__ = [
     "TextEncoder",
     "WaveField",
     "WaveMind",
+    "__version__",
     "create_text_encoder",
 ]

{wavemind-2.0.1 → wavemind-2.0.3}/wavemind/api.py

@@ -6,8 +6,9 @@ from pathlib import Path
 from typing import Any
 
 from fastapi import Body, FastAPI, Query
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, Field
 
+from . import __version__
 from .core import WaveMind
 from .encoders import create_text_encoder
 from .importers import import_path
@@ -30,7 +31,7 @@ class RememberResponse(BaseModel):
 
 
 class QueryRequest(BaseModel):
-    text: str
+    text: str = Field(validation_alias=AliasChoices("text", "query"))
     namespace: str = "default"
     top_k: int = 3
     tags: list[str] = Field(default_factory=list)
@@ -101,7 +102,7 @@ def build_default_mind() -> WaveMind:
 
 def create_app(mind: WaveMind | None = None) -> FastAPI:
     logging.basicConfig(level=os.environ.get("WAVEMIND_LOG_LEVEL", "INFO"))
-    app = FastAPI(title="WaveMind", version="2.0.0")
+    app = FastAPI(title="WaveMind", version=__version__)
     app.state.mind = mind or build_default_mind()
 
     @app.post("/remember", response_model=RememberResponse)

{wavemind-2.0.1 → wavemind-2.0.3}/wavemind/integrations/langchain.py

@@ -11,17 +11,10 @@ from wavemind import WaveMind
 
 try:
     from langchain_classic.base_memory import BaseMemory
-except ImportError:
-    try:
-        from langchain.schema import BaseMemory
-    except ImportError:
-
-        class BaseMemory:
-            """Small fallback so the integration can be imported without LangChain."""
-
-            def __init__(self, **data: Any):
-                for key, value in data.items():
-                    setattr(self, key, value)
+except ImportError as exc:  # pragma: no cover - exercised in clean installs.
+    raise ImportError(
+        'WaveMindMemory requires LangChain. Install it with: pip install "wavemind[langchain]"'
+    ) from exc
 
 
 class WaveMindMemory(BaseMemory):

{wavemind-2.0.1 → wavemind-2.0.3/wavemind.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.0.1
+Version: 2.0.3
 Summary: Persistent dynamic memory engine with vector search and wave-field re-ranking
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaspianG/wavemind
@@ -27,6 +27,7 @@ Requires-Dist: langchain-classic>=1.0; extra == "langchain"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: langchain-classic>=1.0; extra == "dev"
 Dynamic: license-file
 
 # WaveMind is persistent dynamic memory for AI agents: vector search first, wave-field priority second, SQLite as the source of truth.
@@ -37,6 +38,8 @@ Dynamic: license-file
 
 ## Terminal Demo
 
+From a cloned repository:
+
 ```text
 $ python examples/demo.py
 ✓ Remembered: "Andrey is a trader who tracks market breakouts."
@@ -51,23 +54,66 @@ 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 -e .
+python -m pip install wavemind
 wavemind remember "Andrey is a trader" --namespace demo
 wavemind query "trader" --namespace demo
 ```
 
-This creates `wavemind.sqlite3` in your current working directory.
+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:
 
 ```sh
-python -m pip install -e ".[sentence]"
+python -m pip install "wavemind[sentence]"
 wavemind --encoder sentence remember "Andrey is a trader" --namespace demo
 wavemind --encoder sentence query "What does Andrey do?" --namespace demo
 ```
 
-One-file setup scripts are also included:
+## Data Location
+
+For an explicit database path, put global options before the command:
+
+```sh
+wavemind --db ./agent_memory.sqlite3 remember "Andrey is a trader" --namespace demo
+wavemind --db ./agent_memory.sqlite3 query "trader" --namespace demo
+```
+
+## HTTP API
+
+Run the local FastAPI server:
+
+```sh
+wavemind --db ./agent_memory.sqlite3 serve --host 127.0.0.1 --port 8000
+```
+
+Store and query memory over HTTP:
+
+```sh
+curl -X POST http://127.0.0.1:8000/remember -H "Content-Type: application/json" -d "{\"text\":\"Andrey is a trader\",\"namespace\":\"demo\"}"
+curl -X POST http://127.0.0.1:8000/query -H "Content-Type: application/json" -d "{\"query\":\"trader\",\"namespace\":\"demo\",\"top_k\":1}"
+```
+
+## Install From Source
+
+For contributors installing from a local clone:
+
+```sh
+git clone https://github.com/CaspianG/wavemind.git
+cd wavemind
+python -m pip install -e ".[sentence]"
+```
+
+One-file setup scripts are also included in the repository:
 
 ```sh
 sh install.sh
@@ -94,12 +140,41 @@ memory = WaveMindMemory(db_path="agent_memory.sqlite3")
 # Replace: memory = ConversationBufferMemory()
 ```
 
-Offline runnable example:
+Offline runnable example from a cloned repository:
 
 ```sh
 python examples/langchain_memory.py
 ```
 
+## Why Dynamic Memory
+
+WaveMind is not positioned as "a faster Chroma." Chroma, Qdrant, Pinecone, and Weaviate are vector databases: they store embeddings and return nearest neighbors. That is the right tool for many static RAG workloads.
+
+WaveMind is an agent memory layer. It still uses vector search first, but then applies memory-specific signals that a plain vector store does not model by default:
+
+| memory behavior | Why it matters for agents | WaveMind mechanism |
+|---|---|---|
+| Hot memories | Facts recalled repeatedly should become easier to recall again. | Wave-field hotness and priority updates. |
+| Aging memories | Old low-value facts should fade instead of competing forever. | TTL and decay-aware scoring. |
+| Scoped memory | One user, agent, workspace, or project should not leak into another. | Namespaces and tags. |
+| Explicit forgetting | Agents need deletion, privacy cleanup, and correction workflows. | `forget()` plus SQLite persistence. |
+| Stable restart behavior | A memory system must survive process restarts. | SQLite source of truth, reloadable indexes. |
+| Vector plus memory rank | Semantic similarity is necessary but not sufficient for long-running agents. | k-NN candidates first, wave field as re-ranker. |
+
+The current Chroma benchmark below is intentionally conservative: it compares static retrieval on the same facts and the same hash embeddings. That benchmark is useful, but it does not exercise WaveMind's main product thesis: memory that changes over time as an agent recalls, reinforces, ages, and forgets information.
+
+The benchmark that should decide whether WaveMind is worth using is a dynamic agent-memory benchmark:
+
+| scenario | What should happen |
+|---|---|
+| A user repeats a preference many times. | WaveMind should rank it higher than equally similar but unused facts. |
+| A fact expires via TTL. | WaveMind should suppress it without requiring manual vector cleanup. |
+| A user corrects an old fact. | WaveMind should prefer the newer or reinforced memory. |
+| A query is ambiguous across namespaces. | WaveMind should return only the scoped user's memory. |
+| A long conversation has many irrelevant facts. | WaveMind should preserve useful recall instead of treating all vectors equally. |
+
+In short: static vector search answers "what is nearest?" Agent memory also asks "what is still relevant, reinforced, scoped, and allowed to be remembered?"
+
 ## Benchmark
 
 Real Russian sentences from Tatoeba, 50 one-word queries, NumPy exact index.
@@ -118,7 +193,7 @@ Capacity check with the hash encoder:
 | 1000 | 0.88 | 1.00 | 1.50 ms |
 | 5000 | 0.72 | 0.88 | 5.68 ms |
 
-Run locally:
+Run locally from a cloned repository:
 
 ```sh
 python benchmarks/ru_sentences_benchmark.py --sentences 200 --queries 50 --encoder hash --index numpy
@@ -130,12 +205,14 @@ Agent-memory benchmark against Chroma:
 200 Russian user facts, 50 natural-language questions, same precomputed `HashingTextEncoder` embeddings for WaveMind and Chroma.
 Full machine-readable result: `benchmarks/agent_memory_results.json`.
 
+This is a static retrieval benchmark. It measures baseline ranking and latency, not hotness, TTL, repeated recall, or memory aging.
+
 | engine | precision@1 | precision@3 | avg latency |
 |---|---:|---:|---:|
 | WaveMind | 0.82 | 0.90 | 2.25 ms |
 | Chroma | 0.82 | 0.88 | 0.93 ms |
 
-Run locally:
+Run locally from a cloned repository:
 
 ```sh
 pip install -e ".[bench]"
@@ -154,7 +231,7 @@ python benchmarks/agent_memory_benchmark.py --engines wavemind chroma --facts 20
 | Best fit | Small to medium agent memory with dynamic recall | Local RAG apps and prototypes | Large-scale vector search |
 | Scale target today | Up to 1000 optimal on NumPy, FAISS recommended beyond 5000 | Larger than WaveMind local mode | Production scale |
 
-WaveMind is not trying to replace dedicated vector databases at scale. Its difference is dynamic priority: frequently used memories can become hotter while old or low-priority memories fade.
+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 agent memory that needs persistence, scoped recall, TTL, forgetting, and reinforcement, WaveMind is designed to sit above or beside the vector index.
 
 ## Known Limitations
 
@@ -164,10 +241,12 @@ WaveMind is not trying to replace dedicated vector databases at scale. Its diffe
 - `sentence-transformers/paraphrase-multilingual-mpnet-base-v2` requires about 420 MB of model files and measured about 53 ms per query on the benchmark machine.
 - The Chroma comparison currently uses shared precomputed hash embeddings to isolate retrieval/ranking behavior; semantic model comparisons should be run separately.
 - In the 200-fact agent benchmark, Chroma is faster on average while WaveMind is slightly higher at `precision@3`.
+- The current public benchmark does not yet prove the dynamic-memory advantage. The next benchmark must test hotness, TTL, corrections, namespace isolation, and repeated recall.
 
 ## Roadmap
 
 - FAISS-first production index path with persisted index rebuilds.
+- Dynamic agent-memory benchmark against Chroma/Qdrant: hotness, TTL, stale-fact suppression, corrections, and namespace isolation.
 - Expand the agent-memory benchmark to sentence-transformers, FAISS, Chroma default embeddings, and Qdrant.
 - Better semantic query expansion for short and ambiguous queries.
 - Namespace quotas, backups, and daemon hardening for SaaS use.

{wavemind-2.0.1 → wavemind-2.0.3}/wavemind.egg-info/requires.txt

@@ -10,6 +10,7 @@ chromadb>=1.0
 [dev]
 pytest>=8
 httpx>=0.27
+langchain-classic>=1.0
 
 [indexes]
 annoy>=1.17