wavemind 2.1.1__tar.gz → 2.2.1__tar.gz

{wavemind-2.1.1 → wavemind-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavemind
-Version: 2.1.1
+Version: 2.2.1
 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
@@ -68,6 +68,7 @@ users or projects isolated.
 
 [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) |
@@ -139,6 +140,12 @@ Need a reminder after install?
 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.
@@ -152,6 +159,7 @@ Start here if you only want to use WaveMind from the terminal:
 | 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` |
@@ -161,6 +169,33 @@ Start here if you only want to use WaveMind from the terminal:
 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

{wavemind-2.1.1 → wavemind-2.2.1}/README.md

@@ -18,6 +18,7 @@ users or projects isolated.
 
 [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) |
@@ -89,6 +90,12 @@ Need a reminder after install?
 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.
@@ -102,6 +109,7 @@ Start here if you only want to use WaveMind from the terminal:
 | 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` |
@@ -111,6 +119,33 @@ Start here if you only want to use WaveMind from the terminal:
 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

{wavemind-2.1.1 → wavemind-2.2.1}/docker-compose.yml

@@ -4,7 +4,7 @@ services:
       context: .
       args:
         INSTALL_OPTIONAL: "false"
-    image: wavemind:2.1.1
+    image: wavemind:2.2.1
     restart: unless-stopped
     environment:
       WAVEMIND_DB: /data/wavemind.sqlite3

{wavemind-2.1.1 → wavemind-2.2.1}/pyproject.toml

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

{wavemind-2.1.1 → wavemind-2.2.1}/tests/test_api.py

@@ -119,6 +119,69 @@ def test_fastapi_query_accepts_query_alias(tmp_path):
         mind.close()
 
 
+def test_fastapi_studio_dashboard_state_heatmap_and_feedback(tmp_path):
+    mind = WaveMind(
+        db_path=tmp_path / "studio.sqlite3",
+        width=32,
+        height=32,
+        layers=2,
+        encoder=HashingTextEncoder(vector_dim=64),
+    )
+    try:
+        memory_id = mind.remember(
+            "Andrey prefers WaveMind Studio for visual memory inspection",
+            namespace="studio",
+            tags=["ui"],
+            metadata={"conflict_group": "preference.ui"},
+        )
+        mind.remember(
+            "Andrey prefers terminal-only memory inspection",
+            namespace="studio",
+            tags=["ui"],
+            metadata={"conflict_group": "preference.ui"},
+        )
+        before = mind.store.get(memory_id)
+        assert before is not None
+
+        with TestClient(create_app(mind=mind)) as client:
+            page = client.get("/studio")
+            assert page.status_code == 200
+            assert "WaveMind Studio" in page.text
+
+            state = client.get("/studio/state", params={"namespace": "studio"})
+            assert state.status_code == 200
+            payload = state.json()
+            assert "studio" in payload["namespaces"]
+            assert payload["stats"]["active_memories"] == 2
+            assert payload["memories"][0]["namespace"] == "studio"
+            assert payload["conflict_groups"][0]["group"] == "preference.ui"
+
+            fallback_state = client.get("/studio/state", params={"namespace": "default"})
+            assert fallback_state.status_code == 200
+            assert fallback_state.json()["selected_namespace"] == "studio"
+            assert fallback_state.json()["memories"][0]["namespace"] == "studio"
+
+            heatmap = client.get("/studio/heatmap", params={"bins": 8})
+            assert heatmap.status_code == 200
+            heatmap_payload = heatmap.json()
+            assert heatmap_payload["bins"] == 8
+            assert len(heatmap_payload["values"]) == 64
+            assert max(heatmap_payload["values"]) <= 1.0
+
+            feedback = client.post(
+                "/studio/feedback",
+                json={"id": memory_id, "useful": True, "strength": 0.5},
+            )
+            assert feedback.status_code == 200
+            after = mind.store.get(memory_id)
+            assert after is not None
+            assert after.priority > before.priority
+            assert after.access_count == before.access_count + 1
+            assert mind.audit_events(namespace="studio", action="feedback", limit=1)
+    finally:
+        mind.close()
+
+
 def test_fastapi_version_matches_package_version():
     mind = WaveMind(
         db_path=None,

{wavemind-2.1.1 → wavemind-2.2.1}/tests/test_cli_smoke.py

@@ -118,6 +118,7 @@ def test_legacy_script_delegates_to_new_cli(tmp_path):
         check=True,
     )
     assert "WaveMind" in result.stdout
+    assert "studio" in result.stdout
 
 
 def test_cli_benchmark_seeds_all_synthetic_cases(tmp_path):
@@ -145,6 +146,7 @@ def test_cli_quickstart_prints_first_run_commands():
     assert "python -m pip install wavemind" in result.stdout
     assert 'wavemind remember "Andrey is a trader" --namespace demo' in result.stdout
     assert 'wavemind query "What does Andrey do?" --namespace demo' in result.stdout
+    assert "wavemind studio" in result.stdout
 
 
 def test_cli_version_prints_package_version():

{wavemind-2.1.1 → wavemind-2.2.1}/wavemind/__init__.py

@@ -17,7 +17,7 @@ from .storage import (
     create_memory_store,
 )
 
-__version__ = "2.1.1"
+__version__ = "2.2.1"
 
 __all__ = [
     "FieldProjector",

{wavemind-2.1.1 → wavemind-2.2.1}/wavemind/api.py

@@ -9,7 +9,7 @@ from threading import Lock
 from typing import Any
 
 from fastapi import Body, Depends, FastAPI, HTTPException, Query, Request
-from fastapi.responses import JSONResponse, PlainTextResponse
+from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
 from pydantic import AliasChoices, BaseModel, Field
 
 from . import __version__
@@ -17,6 +17,7 @@ from .core import WaveMind
 from .encoders import create_text_encoder
 from .importers import import_path
 from .observability import configure_observability, instrument_fastapi_app
+from .studio import STUDIO_HTML, field_heatmap, studio_snapshot
 
 
 logger = logging.getLogger("wavemind.api")
@@ -205,6 +206,12 @@ class ObservabilityResponse(BaseModel):
     reason: str | None = None
 
 
+class FeedbackRequest(BaseModel):
+    id: int
+    useful: bool = True
+    strength: float = Field(default=0.25, ge=0.0, le=10.0)
+
+
 def _metrics_text(stats: dict[str, Any]) -> str:
     metric_names = {
         "active_memories": "wavemind_active_memories",
@@ -292,6 +299,32 @@ def create_app(mind: WaveMind | None = None) -> FastAPI:
             )
         return await call_next(request)
 
+    @app.get("/studio", response_class=HTMLResponse, include_in_schema=False)
+    def studio() -> HTMLResponse:
+        return HTMLResponse(STUDIO_HTML)
+
+    @app.get("/studio/state", dependencies=[Depends(require_role("read"))])
+    def studio_state(
+        namespace: str | None = None,
+        limit: int = Query(default=200, ge=0, le=1000),
+    ):
+        return studio_snapshot(app.state.mind, namespace=namespace, limit=limit)
+
+    @app.get("/studio/heatmap", dependencies=[Depends(require_role("read"))])
+    def studio_heatmap(bins: int = Query(default=18, ge=4, le=48)):
+        return field_heatmap(app.state.mind, bins=bins)
+
+    @app.post("/studio/feedback", dependencies=[Depends(require_role("write"))])
+    def studio_feedback(request: FeedbackRequest):
+        accepted = app.state.mind.feedback(
+            request.id,
+            useful=request.useful,
+            strength=request.strength,
+        )
+        if not accepted:
+            raise HTTPException(status_code=404, detail="Memory not found")
+        return {"ok": True}
+
     @app.post("/remember", response_model=RememberResponse, dependencies=[Depends(require_role("write"))])
     def remember(request: RememberRequest) -> RememberResponse:
         id = app.state.mind.remember(

{wavemind-2.1.1 → wavemind-2.2.1}/wavemind/cli.py

@@ -128,6 +128,11 @@ def build_parser() -> argparse.ArgumentParser:
     serve.add_argument("--host", default="0.0.0.0")
     serve.add_argument("--port", type=int, default=8000)
 
+    studio = sub.add_parser("studio", help="Run local WaveMind Studio dashboard")
+    studio.add_argument("--host", default="127.0.0.1")
+    studio.add_argument("--port", type=int, default=8000)
+    studio.add_argument("--no-open", action="store_true")
+
     sub.add_parser("test", help="Run pytest suite")
     return parser
 
@@ -177,6 +182,7 @@ Where data goes:
 
 Useful next commands:
   wavemind --help
+  wavemind studio
   wavemind import ./notes.txt --namespace demo
   wavemind serve --host 127.0.0.1 --port 8000
   wavemind forget --namespace demo
@@ -247,6 +253,22 @@ def main(argv: list[str] | None = None) -> int:
         uvicorn.run(create_app(mind=make_mind(args)), host=args.host, port=args.port)
         return 0
 
+    if args.command == "studio":
+        import webbrowser
+        from threading import Timer
+
+        import uvicorn
+
+        from .api import create_app
+
+        open_host = "127.0.0.1" if args.host in {"0.0.0.0", "::"} else args.host
+        url = f"http://{open_host}:{args.port}/studio"
+        print(f"WaveMind Studio: {url}")
+        if not args.no_open:
+            Timer(1.0, lambda: webbrowser.open(url)).start()
+        uvicorn.run(create_app(mind=make_mind(args)), host=args.host, port=args.port)
+        return 0
+
     if args.command == "restore":
         destination = Path(args.destination) if args.destination else (
             Path(args.db) if args.db else Path.cwd() / "wavemind.sqlite3"

{wavemind-2.1.1 → wavemind-2.2.1}/wavemind/core.py

@@ -439,6 +439,45 @@ class WaveMind:
             )
         return len(records)
 
+    def feedback(
+        self,
+        id: int,
+        useful: bool = True,
+        strength: float = 0.25,
+    ) -> bool:
+        record = self._records_by_id.get(int(id))
+        if record is None or record.is_expired:
+            return False
+        delta = abs(float(strength))
+        if useful:
+            record.priority += delta
+            record.access_count += 1
+            self.field.feed(record.pattern, strength=delta)
+        else:
+            record.priority = max(0.0, record.priority - delta)
+            self.field.forget(record.pattern, strength=delta)
+        update_memory_state = getattr(self.store, "update_memory_state", None)
+        if callable(update_memory_state):
+            update_memory_state(
+                record.id,
+                priority=record.priority,
+                access_count=record.access_count,
+            )
+        self.field.evolve(1)
+        self._refresh_field_magnitude()
+        self.store.log_audit_event(
+            "feedback",
+            namespace=record.namespace,
+            memory_id=record.id,
+            metadata={
+                "useful": bool(useful),
+                "strength": delta,
+                "priority": float(record.priority),
+                "access_count": int(record.access_count),
+            },
+        )
+        return True
+
     def save(
         self,
         backup_path: str | Path | None = None,

{wavemind-2.1.1 → wavemind-2.2.1}/wavemind/storage.py

@@ -244,6 +244,32 @@ class SQLiteMemoryStore:
         )
         self.conn.commit()
 
+    def update_memory_state(
+        self,
+        id: int,
+        *,
+        priority: float | None = None,
+        access_count: int | None = None,
+    ) -> None:
+        fields = []
+        params: list[Any] = []
+        if priority is not None:
+            fields.append("priority = ?")
+            params.append(float(priority))
+        if access_count is not None:
+            fields.append("access_count = ?")
+            params.append(int(access_count))
+        if not fields:
+            return
+        fields.append("updated_at = ?")
+        params.append(time.time())
+        params.append(int(id))
+        self.conn.execute(
+            f"UPDATE memories SET {', '.join(fields)} WHERE id = ?",
+            params,
+        )
+        self.conn.commit()
+
     def log_audit_event(
         self,
         action: str,
@@ -643,6 +669,31 @@ class PostgresMemoryStore:
             (float(priority_delta), time.time(), int(id)),
         )
 
+    def update_memory_state(
+        self,
+        id: int,
+        *,
+        priority: float | None = None,
+        access_count: int | None = None,
+    ) -> None:
+        fields = []
+        params: list[Any] = []
+        if priority is not None:
+            fields.append("priority = %s")
+            params.append(float(priority))
+        if access_count is not None:
+            fields.append("access_count = %s")
+            params.append(int(access_count))
+        if not fields:
+            return
+        fields.append("updated_at = %s")
+        params.append(time.time())
+        params.append(int(id))
+        self.conn.execute(
+            f"UPDATE {self.memories_table} SET {', '.join(fields)} WHERE id = %s",
+            params,
+        )
+
     def log_audit_event(
         self,
         action: str,