wavemind 2.0.1__tar.gz → 2.0.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.0.1
+Version: 2.0.2
 Summary: Persistent dynamic memory engine with vector search and wave-field re-ranking
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaspianG/wavemind
@@ -37,6 +37,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 +53,51 @@ 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
+```
+
+## 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 +124,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 +177,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 +189,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 +215,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 +225,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.2}/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,51 @@ 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
+```
+
+## 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 +93,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 +146,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 +158,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 +184,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 +194,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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wavemind"
-version = "2.0.1"
+version = "2.0.2"
 description = "Persistent dynamic memory engine with vector search and wave-field re-ranking"
 readme = "README.md"
 license = "MIT"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.0.1
+Version: 2.0.2
 Summary: Persistent dynamic memory engine with vector search and wave-field re-ranking
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/CaspianG/wavemind
@@ -37,6 +37,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 +53,51 @@ 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
+```
+
+## 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 +124,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 +177,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 +189,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 +215,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 +225,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.