pip install memweave

export OPENAI_API_KEY=sk-...

import asyncio
from pathlib import Path
from memweave import MemWeave, MemoryConfig

async def main():
    async with MemWeave(MemoryConfig(workspace_dir=".")) as mem:
        # Write a memory file, then index it
        memory_file = Path("memory/preferences.md")
        memory_file.parent.mkdir(exist_ok=True)
        memory_file.write_text("The user prefers dark mode and concise answers.")
        await mem.add(memory_file)

        # Search across all memories.
        # min_score=0.0 ensures results surface in a small corpus;
        # in production the default 0.35 threshold filters low-confidence matches.
        results = await mem.search("What is the user preference?", min_score=0.0)
        for r in results:
            print(f"[{r.score:.2f}] {r.snippet}  ← {r.path}:{r.start_line}")

asyncio.run(main())

cat memory/*.md

[0.35] The user prefers dark mode and concise answers.  ← memory/preferences.md:1

┌──────────────────────────────────────────────────────────────┐
│                 SOURCE OF TRUTH  (Markdown files)            │
│   memory/MEMORY.md        ← evergreen knowledge              │
│   memory/2026-03-21.md    ← daily logs                       │
│   memory/agents/coder/    ← agent-scoped namespace           │
└───────────────────────┬──────────────────────────────────────┘
                        │  chunking → hashing → embedding
┌───────────────────────▼──────────────────────────────────────┐
│                DERIVED INDEX  (SQLite)                       │
│   chunks          — text + metadata                          │
│   chunks_fts      — FTS5 full-text index  (BM25)             │
│   chunks_vec      — sqlite-vec SIMD index (cosine)           │
│   embedding_cache — hash → vector  (skip re-embedding)       │
│   files           — SHA-256 change detection                 │
└───────────────────────┬──────────────────────────────────────┘
                        │  hybrid merge → post-processing
                        ▼
              list[SearchResult]

                        query
                          │
             ┌────────────┴────────────┐
             │                         │
     FTS5 BM25 (keyword)      sqlite-vec ANN (semantic)
     exact term matching       cosine similarity
             │                         │
             └────────────┬────────────┘
                          │  weighted merge
                          │  score = 0.7 × vector + 0.3 × BM25
                          │
                 ┌────────▼────────┐
                 │ ScoreThreshold  │  drop results below min_score (default 0.35)
                 └────────┬────────┘
                          │
                 ┌────────▼────────┐
                 │ TemporalDecay   │  multiply score by exp(−λ × age_days)
                 │  (opt-in)       │  evergreen files exempt
                 └────────┬────────┘
                          │
                 ┌────────▼────────┐
                 │  MMR Reranker   │  reorder for relevance + diversity
                 │  (opt-in)       │  λ × relevance − (1−λ) × similarity_to_selected
                 └────────┬────────┘
                          │
                 ┌────────▼────────┐
                 │ Custom          │  your own PostProcessor(s)
                 │ processors      │  via mem.register_postprocessor()
                 └────────┬────────┘
                          │
                   list[SearchResult]

λ            = ln(2) / half_life_days
multiplier   = exp(−λ × age_days)
decayed_score = original_score × multiplier

from memweave import MemWeave
from memweave.config import MemoryConfig, QueryConfig, TemporalDecayConfig

config = MemoryConfig(
    query=QueryConfig(
        temporal_decay=TemporalDecayConfig(
            enabled=True,
            half_life_days=30.0,   # score halves every 30 days; tune to your workflow
        ),
    ),
)

async with MemWeave(config) as mem:
    results = await mem.search("database choice")
    # results from last week will rank above results from last quarter
    # results from memory/MEMORY.md are exempt and always surface at full score

MMR score = λ × relevance − (1−λ) × max_similarity_to_already_selected

from memweave import MemWeave
from memweave.config import MemoryConfig, QueryConfig, MMRConfig

config = MemoryConfig(
    query=QueryConfig(
        mmr=MMRConfig(
            enabled=True,
            lambda_param=0.7,   # 0 = max diversity, 1 = max relevance
        ),
    ),
)

async with MemWeave(config) as mem:
    results = await mem.search("deployment steps")
    # top results will cover different aspects of deployment
    # rather than returning the same facts from multiple angles

    # override λ per-call without touching the config
    diverse = await mem.search("deployment steps", mmr_lambda=0.3)

# Index a workspace
memweave index --workspace ./my_project --embedding-model text-embedding-3-small

# Force re-embed everything regardless of hash
memweave index --workspace ./my_project --embedding-model text-embedding-3-small --force

# Run from the parent of my_project/
memweave add my_project/memory/2026-04-25.md --workspace ./my_project --embedding-model text-embedding-3-small

# Or cd into the workspace first, then the path is relative to CWD
cd my_project
memweave add memory/infrastructure.md --workspace . --embedding-model text-embedding-3-small

# Force re-index even if the file hasn't changed
memweave add my_project/memory/architecture.md --workspace ./my_project --embedding-model text-embedding-3-small --force

# Filter to a specific source namespace
memweave files --workspace ./my_project --source sessions

# Machine-readable output
memweave files --workspace ./my_project --json

# Table view
memweave files --workspace ./my_project

Path                          Source    Chunks  Evergreen
memory/2026-04-25.md          memory        3   no
memory/architecture.md        memory        5   yes
memory/sessions/2026-04-24.md sessions      2   no

# Basic search
memweave search "PostgreSQL JSONB" --workspace ./my_project --embedding-model text-embedding-3-small

# Cap results and set a minimum score
memweave search "caching layer" --workspace ./my_project --max-results 3 --min-score 0.3

# Scope to one source namespace
memweave search "deployment steps" --workspace ./my_project --source-filter sessions --embedding-model text-embedding-3-small

# Use keyword-only search (no embedding API needed)
memweave search "Redis ElastiCache" --workspace ./my_project --strategy keyword

# Control diversity vs relevance with MMR (0 = diverse, 1 = relevant)
memweave search "database choice" --workspace ./my_project --mmr-lambda 0.3 --embedding-model text-embedding-3-small

# Apply temporal decay so older memories rank lower
memweave search "architecture decision" --workspace ./my_project --decay-half-life-days 14 --embedding-model text-embedding-3-small

# JSON output — pipe to jq, save to file, or pass to another tool
memweave search "database choice" --workspace ./my_project --embedding-model text-embedding-3-small --json
memweave search "database choice" --workspace ./my_project --embedding-model text-embedding-3-small --json | jq '.[0].snippet'

Score  Path                          Lines   Source   Preview
 0.91  memory/2026-04-25.md          1–8     memory   PostgreSQL 16 chosen for JSONB support.
 0.74  memory/infrastructure.md      4–11    memory   Production Redis runs on ElastiCache r6g.
 0.61  memory/sessions/findings.md   23–30   sessions Discussed moving from Memcached to Redis.

[
  {
    "path": "memory/2026-04-25.md",
    "start_line": 1,
    "end_line": 8,
    "score": 0.91,
    "snippet": "PostgreSQL 16 chosen for JSONB support.",
    "source": "memory",
    "vector_score": 0.91,
    "text_score": 0.70
  }
]

memweave stats --workspace ./my_project
memweave stats --workspace ./my_project --json

──────────────────────────────────────
  Workspace:        /my_project
  DB path:          /my_project/.memweave/index.sqlite
  Search mode:      hybrid
  Provider:         litellm
  Model:            text-embedding-3-small

  Files:            12
  Chunks:           47
  Cache entries:    47
  Cache max:        unlimited
  Dirty:            no
  Watcher active:   no
  FTS available:    yes
  Vector available: yes

import asyncio
from pathlib import Path
from memweave import MemWeave, MemoryConfig

async def run_agent_session():
    config = MemoryConfig(workspace_dir="./my_project")

    async with MemWeave(config) as mem:
        # Write memory files, then index them
        memory_dir = Path("my_project/memory")
        memory_dir.mkdir(parents=True, exist_ok=True)

        (memory_dir / "stack.md").write_text("User's preferred stack: FastAPI + PostgreSQL + Redis.")
        (memory_dir / "guidelines.md").write_text("Avoid using global state in this codebase.")

        await mem.index()

        # Retrieve relevant context before responding
        context = await mem.search("database recommendations", min_score=0.0, max_results=2)
        for result in context:
            print(f"  [{result.score:.2f}] {result.snippet}  ({result.path}:{result.start_line})")

asyncio.run(run_agent_session())

import asyncio
from pathlib import Path
from memweave import MemWeave, MemoryConfig

async def main():
    # Both agents share the same workspace root
    researcher = MemWeave(MemoryConfig(workspace_dir="./project"))
    writer = MemWeave(MemoryConfig(workspace_dir="./project"))

    async with researcher, writer:
        # Researcher writes space exploration findings to its own namespace
        memory_dir = Path("project/memory/researcher_agent")
        memory_dir.mkdir(parents=True, exist_ok=True)

        (memory_dir / "mars_habitat.md").write_text(
            "Mars surface pressure is ~0.6% of Earth's, requiring fully pressurised habitats. "
            "NASA's MOXIE experiment on Perseverance successfully produced oxygen from CO2 in 2021, "
            "validating in-situ resource utilisation (ISRU) as a viable strategy for long-duration missions."
        )
        (memory_dir / "artemis_mission.md").write_text(
            "Artemis III aims to land the first woman and next man near the lunar south pole. "
            "Permanently shadowed craters there hold water ice deposits confirmed by LCROSS in 2009. "
            "Ice can be electrolysed into hydrogen and oxygen, serving as both breathable air and rocket propellant."
        )
        (memory_dir / "deep_space_propulsion.md").write_text(
            "Ion drives expel charged xenon atoms at ~90,000 km/h, achieving far higher specific impulse "
            "than chemical rockets, though thrust is measured in millinewtons. NASA's Dawn spacecraft used "
            "ion propulsion to orbit both Vesta and Ceres — the first mission to orbit two extraterrestrial bodies."
        )

        await researcher.index()

        # Writer queries the researcher's findings — scoped to the researcher_agent source
        queries = [
            "how do astronauts get oxygen on Mars",
            "water ice on the Moon",
            "spacecraft propulsion beyond chemical rockets",
        ]

        for query in queries:
            print(f"\nQuery: {query!r}")
            results = await writer.search(query, source_filter="researcher_agent", min_score=0.0, max_results=1)
            for r in results:
                print(f"  [{r.score:.2f}] {r.snippet}  ({r.path}:{r.start_line})")

asyncio.run(main())

import asyncio
from pathlib import Path
from memweave import MemWeave, MemoryConfig

WORKSPACE = Path(__file__).parent / "workspace"

conversation = [
    {"role": "user",      "content": "We just decided to use Valkey instead of Redis for caching."},
    {"role": "assistant", "content": "Got it. I'll note that Valkey is the new caching layer."},
    {"role": "user",      "content": "Also, we're targeting a 5ms p99 latency SLA for the cache."},
]

async def main():
    config = MemoryConfig(workspace_dir=WORKSPACE)

    async with MemWeave(config) as mem:
        # Extract durable facts from the conversation and write to workspace/memory/YYYY-MM-DD.md.
        # Returns the extracted text, or None if there was nothing worth storing.
        extracted = await mem.flush(conversation=conversation)
        if extracted:
            print(f"Stored:\n{extracted}\n")
        else:
            print("Nothing worth storing.\n")

        # Search the indexed knowledge immediately after flush
        results = await mem.search("Valkey caching latency", min_score=0.0)
        print(f"Search results ({len(results)} hits):")
        for r in results:
            print(f"  [{r.score:.3f}] {r.snippet.strip()}")

asyncio.run(main())

import asyncio
import aiosqlite
from memweave import MemWeave, MemoryConfig
from memweave.search.strategy import RawSearchRow

class RecencyBoostStrategy:
    async def search(
        self,
        db: aiosqlite.Connection,
        query: str,
        query_vec: list[float] | None,
        model: str,
        limit: int,
        *,
        source_filter: str | None = None,
    ) -> list[RawSearchRow]:
        # Your custom ranking logic here — query `db` directly and return RawSearchRow objects
        ...

async def main():
    async with MemWeave(MemoryConfig(workspace_dir=".")) as mem:
        mem.register_strategy("recency", RecencyBoostStrategy())
        results = await mem.search("recent decisions", strategy="recency")

asyncio.run(main())

import asyncio
from memweave import MemWeave

async def main():
    async with MemWeave() as mem:
        await mem.start_watching()   # starts background task, watches memory/
        # ... run your agent loop
        # any .md file edits are picked up and re-indexed automatically
        # watcher stops automatically on context manager exit

asyncio.run(main())

async with MemWeave() as mem:
    status = await mem.status()
    print(f"Files:       {status.files}")
    print(f"Chunks:      {status.chunks}")
    print(f"Search mode: {status.search_mode}")   # hybrid | fts-only | vector-only
    print(f"Dirty:       {status.dirty}")         # unindexed changes pending

async with MemWeave() as mem:
    for f in await mem.files():
        print(f"{f.path}  ({f.chunks} chunks, evergreen={f.is_evergreen}, source={f.source})")

from memweave import MemWeave
from memweave.config import (
    MemoryConfig, EmbeddingConfig, QueryConfig,
    HybridConfig, MMRConfig, TemporalDecayConfig,
    SyncConfig, FlushConfig,
)

config = MemoryConfig(
    workspace_dir="./memory",            # where .md files live

    embedding=EmbeddingConfig(
        model="text-embedding-3-small",  # any LiteLLM-compatible model
        api_key="sk-...",                # or set via environment variable
        batch_size=100,
    ),

    query=QueryConfig(
        strategy="hybrid",               # "hybrid" | "vector" | "keyword"
        max_results=10,
        min_score=0.35,

        hybrid=HybridConfig(
            vector_weight=0.7,           # weight for semantic similarity
            text_weight=0.3,             # weight for BM25 keyword score
        ),

        mmr=MMRConfig(
            enabled=True,
            lambda_param=0.5,            # 0 = max diversity, 1 = max relevance
        ),

        temporal_decay=TemporalDecayConfig(
            enabled=True,
            half_life_days=30.0,         # score halves every 30 days
        ),
    ),

    sync=SyncConfig(
        on_search=True,                  # sync dirty files before each search
        watch=False,                     # enable file watcher
        watch_debounce_ms=500,
    ),

    flush=FlushConfig(
        enabled=True,
        model="gpt-4o-mini",             # LLM used for fact extraction
    ),
)

async with MemWeave(config) as mem:
    ...

from memweave.config import MemoryConfig, EmbeddingConfig

config = MemoryConfig(
    embedding=EmbeddingConfig(
        model="ollama/nomic-embed-text",
        api_base="http://localhost:11434",
    )
)

from memweave.config import MemoryConfig, QueryConfig

config = MemoryConfig(
    query=QueryConfig(strategy="keyword")
)