WaveMind

Adaptive memory infrastructure for agents and applications that need to learn from experience.

WaveMind gives long-running software a durable, inspectable memory layer. It remembers facts, preferences, state changes, workflows, errors, and feedback; returns a compact relevant context; reinforces what works; suppresses stale information; and forgets on purpose.

PyPI · Build status · Latest release · Python >=3.10 · MIT

Quick Start · Documentation · Studio · Benchmarks · Roadmap · Contributing

Vector stores answer what is similar? Agent memory must also answer what still matters now?

WaveMind complements FAISS, Qdrant, pgvector, Chroma, and other candidate indexes. It is the memory policy and lifecycle around retrieval, not another claim that one vector database should replace every other system.

Remote multi-region, managed serverless, 100M service evidence, and universal multimodal admission remain explicitly gated. See Known Limitations and the evidence dashboard.

The shortest path from install to first recall:

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?

wavemind quickstart

Want to see and manage memory in a browser?

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.

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 is the built-in local dashboard. It runs on top of the same FastAPI app and SQLite database as the CLI:

wavemind studio

It opens http://127.0.0.1:8000/studio and gives you:

For a server-safe local bind:

wavemind --db ./state/wavemind.sqlite3 studio --host 127.0.0.1 --port 8000

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.

The FastAPI server is included in the base install:

wavemind --db ./state/wavemind.sqlite3 serve --host 127.0.0.1 --port 8000

Then use WaveMind from any language:

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}"

curl -X POST http://127.0.0.1:8000/feedback \
  -H "Content-Type: application/json" \
  -d "{\"id\":1,\"namespace\":\"user:42\",\"useful\":true,\"strength\":0.5,\"reason\":\"used in answer\"}"

curl -X POST http://127.0.0.1:8000/feedback/batch \
  -H "Content-Type: application/json" \
  -d "{\"namespace\":\"user:42\",\"items\":[{\"id\":1,\"useful\":true,\"strength\":0.5},{\"id\":2,\"useful\":false,\"strength\":0.25}]}"

curl -X POST http://127.0.0.1:8000/forget/batch \
  -H "Content-Type: application/json" \
  -d "{\"items\":[{\"text\":\"Andrey prefers short answers\",\"namespace\":\"user:42\"}]}"

The same feedback loop is available from the CLI:

wavemind --db ./state/wavemind.sqlite3 feedback --id 1 --namespace user:42 --strength 0.5 --reason "used in answer"
wavemind --db ./state/wavemind.sqlite3 feedback-batch --file feedback.json

WaveMind is local-first. The SQLite database stores memories, vectors, metadata, namespaces, tags, TTL, hotness, priority, and audit events.

Explicit path:

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

For migrations from existing local vector memory, start with docs/CHROMA_MIGRATION.md. The guide has a tested offline fixture at examples/chroma_migration.py.

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

From a cloned repository:

$ 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:

python examples/dynamic_memory_demo.py

That demo shows corrected facts outranking stale facts, temporary memory expiring, namespace isolation, and index-health reporting.

To see the same behavior in a practical support/CRM workflow:

python examples/customer_support_memory.py

That demo stores customer preferences, billing tickets, stale CRM data, temporary discount codes, and separate customer namespaces.

To see source-aware research memory:

python examples/research_notebook_memory.py

That demo stores analyst findings, temporary hypotheses, decisions, source metadata, and isolated project namespaces.

flowchart LR
    A["Text, event, note, document, or agent turn"] --> S["remember()"]
    S --> D[("SQLite: text + metadata + vectors + memory state")]
    Q["query()"] --> K["k-NN candidate search"]
    D --> K
    K --> W["wave-field re-rank"]
    W --> R["small ranked recall set"]
    R --> P["app, search UI, prompt, API, or tool"]
    P --> F["recall feedback updates hotness / priority"]
    F --> D
    F --> C["consolidate active clusters"]
    C --> D

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.

Technically, the current MemoryFieldGraph is a discrete graph over stored 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.

Self-organization is now part of the core surface. consolidate_concepts(), wavemind consolidate, and POST /consolidate can turn an active graph cluster into a new stored memory such as Consolidated memory: systems... without an LLM call. The generated memory keeps the source memory ids in metadata, so it is auditable instead of being a hidden summary.

The base install is offline and keyless. Add sentence-transformers when you need semantic embeddings:

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

WaveMind separates durable state from candidate generation:

SQLite or PostgreSQL remains the source of truth. Missing service configuration fails clearly instead of silently switching backends. See Embeddings And Index Backends for setup, tuning, health checks, and persistence rules.

WaveMind ships local and service-backed storage, namespace sharding, replication, Kubernetes/operator manifests, serverless lifecycle checks, backup/restore drills, and strict evidence gates. The current production evidence gate passes 5/8 requirements; remote active-active, managed serverless telemetry, and a real 100M sharded run remain explicitly locked.

The Checked-in production 50000-vector point covers WaveMind faiss-persisted, Qdrant service, and pgvector tuning with WAVEMIND_PGVECTOR_EF_SEARCH=400, pgvector-exact, and pgvector-iterative.

Deployment references use ghcr.io/caspiang/wavemind. The deploy/cloud/gcp-managed-serverless module creates billable Google Cloud resources. deploy/cloud/gcp-remote-active-active also creates billable infrastructure and does not unlock a production claim by itself. deploy/cloud/gcp-qdrant-100m creates eight billable VMs; planning or applying that module does not unlock the 100M claim without the measured artifact.

See Scale And Production for deployment modes, failure drills, strict claim boundaries, and exact reproduction commands. See Observability for metrics, traces, dashboards, and alerts.

WaveMind supports typed image, audio, video, 3D, table, temporal-event, and knowledge-graph payloads. Current checked evidence proves the structured contract and the explicitly precomputed-vector storage path. Precomputed vectors do not prove encoder quality and cannot unlock production multimodal admission.

The production gate requires real local text, image, audio, video, and 3D encoders over at least 1000 real or publicly licensed assets and 200 independent queries. It also requires explicit compatible shared spaces, bidirectional cross-modal checks, per-modality quality and encoding budgets, stable repeated verdicts, and a verified S3-compatible lifecycle. Local MinIO is valid; descriptor, filename, metadata, OCR-only, synthetic-vector, and precomputed shortcuts are rejected as encoder evidence.

See Multimodal And Storage for payload schemas, cross-modal retrieval, temporal and graph queries, storage backends, object lifecycles, backup/restore, and API details.

Start the API with:

wavemind serve --host 127.0.0.1 --port 8000

The service exposes memory, feedback, lifecycle, health, metrics, cluster, and Memory OS routes. Production deployments should enable authentication, rate limits, TLS termination, durable storage, and monitoring. The complete route reference is in Multimodal And Storage.

For contributors installing from a local clone:

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 install.sh

install.bat

WaveMind includes package adapters for LangChain, LangGraph, LlamaIndex, CrewAI, and AutoGen. The adapters preserve namespaces and use the same durable memory API as the CLI and HTTP service.

See Framework Integrations for complete examples, OpenClaw/Hermes guidance, and custom agent loops.

Experimental work stays isolated from release claims. In particular, research/crypto-pattern-memory is an evidence-gated research branch and is not part of the stable package or current production claims.

WaveMind publishes checked-in JSON and Markdown artifacts for dynamic-memory, long-term-memory, indexing, scale, Memory OS, and production-evidence profiles. The public leaderboard separates implemented, runner-ready, planned, local, loopback, and production evidence.

These results do not claim universal vector-database leadership or completed remote 100M/multi-region proof. See the full Benchmark Guide, living dashboard, and Benchmark Brief for methods, commands, limitations, and machine-readable artifacts.

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.

• The default NumPy exact index is intended for local memory streams. Run wavemind scale-plan and move to FAISS, Qdrant, or pgvector before treating it as a large-N production index.
• Dynamic memory policy adds latency compared with static nearest-neighbor retrieval. The value is stale suppression, reinforcement, TTL, scoped recall, and consolidation rather than winning every pure ANN latency test.
• MemoryFieldGraph is a discrete graph over stored memories, not a continuous physics field.
• Production Memory OS is admitted for its documented remote Redis/worker topology. The broader cluster gate remains 5/8: remote multi-region, managed serverless telemetry, and 100M service evidence are not yet admitted.
• Real universal text/image/audio/video/3D encoding and cross-modal quality are still behind multimodal-admission; precomputed vectors and descriptors do not unlock that claim.
• Large-N Qdrant and pgvector artifacts prove their stated GitHub-hosted service topologies, not independent multi-host or multi-region production.

Read the complete Known Limitations And Claim Boundaries before publishing performance, scale, or multimodal claims.

Full roadmap: docs/ROADMAP.md. Launch and positioning kit: docs/LAUNCH_KIT.md. Documentation map: docs/README.md. Release history: CHANGELOG.md.

Near-term priorities:

• Finish real local text, image, audio, video, and 3D encoders and pass the strict multimodal admission gate without descriptor or synthetic-vector fallbacks.
• Run Memory OS directly inside LoCoMo, LongMemEval, and LongMemEval-V2 evaluations and prove agent-quality lift against reproducible local baselines.
• Improve dynamic re-ranking latency, context efficiency, and cost without weakening stale suppression, provenance, or recall quality.
• Expand production operations with stronger index-health metrics, alerting examples, and externally executed disaster-recovery evidence.
• Complete the remaining cluster evidence on real non-loopback infrastructure: multi-region active-active, managed serverless telemetry, and 100M service load.

Longer-term direction:

• make adaptive memory improve real agent workflows, not only retrieval metrics;
• preserve one provenance-aware lifecycle across text, media, structured data, temporal events, and knowledge graphs;
• scale from a private local database to replicated production deployments without changing the application-level memory contract;
• keep every public capability tied to a reproducible artifact, gate, or clearly locked claim.

Contributing guide: CONTRIBUTING.md. Community participation follows the CODE_OF_CONDUCT.md.

Useful contribution paths:

• add reproducible benchmark adapters and checked-in result JSON;
• improve FAISS, Qdrant, pgvector, or other candidate-index backends;
• add examples for LangGraph, LlamaIndex, CrewAI, AutoGen, OpenClaw, and HTTP-only sidecar deployments;
• improve dynamic memory behavior around TTL, corrections, namespaces, graph excitation/inhibition, and consolidation;
• harden production operations: backups, audit logs, metrics, tracing, and migration tools.

GitHub issue templates are included for bugs, features, benchmarks, and integrations. Benchmark claims need a reproduction command and committed result artifact before they are added to README.

MIT. See LICENSE.