memsearch 0.1.8

Semantic memory search for markdown knowledge bases

  memsearch

OpenClaw's memory, everywhere.

https://github.com/user-attachments/assets/31de76cc-81a8-4462-a47d-bd9c394d33e3

💡 Give your AI agents persistent memory in a few lines of code. Write memories as markdown, search them semantically. Inspired by OpenClaw's markdown-first memory architecture. Pluggable into any agent framework.

✨ Why memsearch?

• 📝 Markdown is the source of truth — human-readable, git-friendly, zero vendor lock-in. Your memories are just .md files
• ⚡ Smart dedup — SHA-256 content hashing means unchanged content is never re-embedded
• 🔄 Live sync — File watcher auto-indexes changes to the vector DB, deletes stale chunks when files are removed
• 🧩 Ready-made Claude Code plugin — a drop-in example of agent memory built on memsearch

📦 Installation

pip install memsearch

Optional embedding providers

pip install "memsearch[google]"      # Google Gemini
pip install "memsearch[voyage]"      # Voyage AI
pip install "memsearch[ollama]"      # Ollama (local)
pip install "memsearch[local]"       # sentence-transformers (local, no API key)
pip install "memsearch[all]"         # Everything

🐍 Python API — Give Your Agent Memory

from memsearch import MemSearch

mem = MemSearch(paths=["./memory"])

await mem.index()                                      # index markdown files
results = await mem.search("Redis config", top_k=3)    # semantic search
print(results[0]["content"], results[0]["score"])       # content + similarity

🚀 Full example — agent with memory (OpenAI) — click to expand

import asyncio
from datetime import date
from pathlib import Path
from openai import OpenAI
from memsearch import MemSearch

MEMORY_DIR = "./memory"
llm = OpenAI()                                        # your LLM client
mem = MemSearch(paths=[MEMORY_DIR])                    # memsearch handles the rest

def save_memory(content: str):
    """Append a note to today's memory log (OpenClaw-style daily markdown)."""
    p = Path(MEMORY_DIR) / f"{date.today()}.md"
    p.parent.mkdir(parents=True, exist_ok=True)
    with open(p, "a") as f:
        f.write(f"\n{content}\n")

async def agent_chat(user_input: str) -> str:
    # 1. Recall — search past memories for relevant context
    memories = await mem.search(user_input, top_k=3)
    context = "\n".join(f"- {m['content'][:200]}" for m in memories)

    # 2. Think — call LLM with memory context
    resp = llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"You have these memories:\n{context}"},
            {"role": "user", "content": user_input},
        ],
    )
    answer = resp.choices[0].message.content

    # 3. Remember — save this exchange and index it
    save_memory(f"## {user_input}\n{answer}")
    await mem.index()

    return answer

async def main():
    # Seed some knowledge
    save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
    save_memory("## Decision\nWe chose Redis for caching over Memcached.")
    await mem.index()  # or mem.watch() to auto-index in the background

    # Agent can now recall those memories
    print(await agent_chat("Who is our frontend lead?"))
    print(await agent_chat("What caching solution did we pick?"))

asyncio.run(main())

💜 Anthropic Claude example — click to expand

pip install memsearch anthropic

import asyncio
from datetime import date
from pathlib import Path
from anthropic import Anthropic
from memsearch import MemSearch

MEMORY_DIR = "./memory"
llm = Anthropic()
mem = MemSearch(paths=[MEMORY_DIR])

def save_memory(content: str):
    p = Path(MEMORY_DIR) / f"{date.today()}.md"
    p.parent.mkdir(parents=True, exist_ok=True)
    with open(p, "a") as f:
        f.write(f"\n{content}\n")

async def agent_chat(user_input: str) -> str:
    # 1. Recall
    memories = await mem.search(user_input, top_k=3)
    context = "\n".join(f"- {m['content'][:200]}" for m in memories)

    # 2. Think — call Claude with memory context
    resp = llm.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=1024,
        system=f"You have these memories:\n{context}",
        messages=[{"role": "user", "content": user_input}],
    )
    answer = resp.content[0].text

    # 3. Remember
    save_memory(f"## {user_input}\n{answer}")
    await mem.index()
    return answer

async def main():
    save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
    await mem.index()
    print(await agent_chat("Who is our frontend lead?"))

asyncio.run(main())

🦙 Ollama (fully local, no API key) — click to expand

pip install "memsearch[ollama]"
ollama pull nomic-embed-text          # embedding model
ollama pull llama3.2                  # chat model

import asyncio
from datetime import date
from pathlib import Path
from ollama import chat
from memsearch import MemSearch

MEMORY_DIR = "./memory"
mem = MemSearch(paths=[MEMORY_DIR], embedding_provider="ollama")

def save_memory(content: str):
    p = Path(MEMORY_DIR) / f"{date.today()}.md"
    p.parent.mkdir(parents=True, exist_ok=True)
    with open(p, "a") as f:
        f.write(f"\n{content}\n")

async def agent_chat(user_input: str) -> str:
    # 1. Recall
    memories = await mem.search(user_input, top_k=3)
    context = "\n".join(f"- {m['content'][:200]}" for m in memories)

    # 2. Think — call Ollama locally
    resp = chat(
        model="llama3.2",
        messages=[
            {"role": "system", "content": f"You have these memories:\n{context}"},
            {"role": "user", "content": user_input},
        ],
    )
    answer = resp.message.content

    # 3. Remember
    save_memory(f"## {user_input}\n{answer}")
    await mem.index()
    return answer

async def main():
    save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
    await mem.index()
    print(await agent_chat("Who is our frontend lead?"))

asyncio.run(main())

🖥️ CLI Usage

Set Up — config init

Interactive wizard to configure embedding provider, Milvus backend, and chunking parameters:

memsearch config init                    # write to ~/.memsearch/config.toml
memsearch config init --project          # write to .memsearch.toml (per-project)
memsearch config set milvus.uri http://localhost:19530
memsearch config list --resolved         # show merged config from all sources

Index Markdown — index

Scan directories and embed all markdown into the vector store. Unchanged chunks are auto-skipped via content-hash dedup:

memsearch index ./memory/
memsearch index ./memory/ ./notes/ --provider google
memsearch index ./memory/ --force        # re-embed everything

Semantic Search — search

Hybrid search (dense vector + BM25 full-text) with RRF reranking:

memsearch search "how to configure Redis caching"
memsearch search "auth flow" --top-k 10 --json-output

Live Sync — watch

File watcher that auto-indexes on markdown changes (creates, edits, deletes):

memsearch watch ./memory/
memsearch watch ./memory/ ./notes/ --debounce-ms 3000

LLM Summarization — compact

Compress indexed chunks into a condensed markdown summary using an LLM:

memsearch compact
memsearch compact --llm-provider anthropic --source ./memory/old-notes.md

Utilities — stats / reset

memsearch stats                          # show total indexed chunk count
memsearch reset                          # drop all indexed data (with confirmation)

📖 Full command reference with all flags and examples → CLI Reference

🔍 How It Works

Markdown is the source of truth — the vector store is just a derived index, rebuildable anytime.

  ┌─── Search ─────────────────────────────────────────────────────────┐
  │                                                                    │
  │  "how to configure Redis?"                                         │
  │        │                                                           │
  │        ▼                                                           │
  │   ┌──────────┐     ┌─────────────────┐     ┌──────────────────┐   │
  │   │  Embed   │────▶│ Cosine similarity│────▶│ Top-K results    │   │
  │   │  query   │     │ (Milvus)        │     │ with source info │   │
  │   └──────────┘     └─────────────────┘     └──────────────────┘   │
  │                                                                    │
  └────────────────────────────────────────────────────────────────────┘

  ┌─── Ingest ─────────────────────────────────────────────────────────┐
  │                                                                    │
  │  MEMORY.md                                                         │
  │  memory/2026-02-09.md     ┌──────────┐     ┌────────────────┐     │
  │  memory/2026-02-08.md ───▶│ Chunker  │────▶│ Dedup          │     │
  │                           │(heading, │     │(chunk_hash PK) │     │
  │                           │paragraph)│     └───────┬────────┘     │
  │                           └──────────┘             │              │
  │                                             new chunks only       │
  │                                                    ▼              │
  │                                            ┌──────────────┐       │
  │                                            │  Embed &     │       │
  │                                            │  Milvus upsert│      │
  │                                            └──────────────┘       │
  │                                                                    │
  └────────────────────────────────────────────────────────────────────┘

  ┌─── Watch ──────────────────────────────────────────────────────────┐
  │  File watcher (1500ms debounce) ──▶ auto re-index / delete stale  │
  └────────────────────────────────────────────────────────────────────┘

  ┌─── Compact ─────────────────────────────────────────────────────────┐
  │  Retrieve chunks ──▶ LLM summarize ──▶ write memory/YYYY-MM-DD.md │
  └────────────────────────────────────────────────────────────────────┘

🔒 The entire pipeline runs locally by default — your data never leaves your machine unless you choose a remote backend or a cloud embedding provider.

🧩 Claude Code Plugin

memsearch ships with a Claude Code plugin — a real-world example of agent memory in action. It gives Claude automatic persistent memory across sessions: every session is summarized to markdown, every prompt triggers a semantic search, and a background watcher keeps the index in sync. No commands to learn, no manual saving — just install and go.

# 1. Install the memsearch CLI
pip install memsearch

# 2. Set your embedding API key (OpenAI is the default provider)
export OPENAI_API_KEY="sk-..."

# 3. In Claude Code, add the marketplace and install the plugin
/plugin marketplace add zilliztech/memsearch
/plugin install memsearch

# 4. Restart Claude Code for the plugin to take effect, then start chatting!
claude

📖 Architecture, hook details, and development mode → Claude Code Plugin docs

⚙️ Configuration

Settings are resolved in priority order (lowest → highest):

1. Built-in defaults → 2. Global ~/.memsearch/config.toml → 3. Project .memsearch.toml → 4. CLI flags

API keys for embedding/LLM providers are read from standard environment variables (OPENAI_API_KEY, GOOGLE_API_KEY, VOYAGE_API_KEY, ANTHROPIC_API_KEY, etc.).

📖 Config wizard, TOML examples, and all settings → Getting Started — Configuration

🔌 Embedding Providers

Provider	Install	Default Model
OpenAI	memsearch (included)	text-embedding-3-small
Google	memsearch[google]	gemini-embedding-001
Voyage	memsearch[voyage]	voyage-3-lite
Ollama	memsearch[ollama]	nomic-embed-text
Local	memsearch[local]	all-MiniLM-L6-v2

📖 Provider setup and env vars → CLI Reference — Embedding Provider Reference

🗄️ Milvus Backend

memsearch supports three deployment modes — just change milvus_uri:

Mode	milvus_uri	Best for
Milvus Lite (default)	~/.memsearch/milvus.db	Personal use, dev — zero config
Milvus Server	http://localhost:19530	Multi-agent, team environments
Zilliz Cloud	https://in03-xxx.api.gcp-us-west1.zillizcloud.com	Production, fully managed

📖 Code examples and setup details → Getting Started — Milvus Backends

🔗 Integrations

memsearch works with any Python agent framework. Ready-made examples for:

• LangChain — use as a BaseRetriever in any LCEL chain
• LangGraph — wrap as a tool in a ReAct agent
• LlamaIndex — plug in as a custom retriever
• CrewAI — add as a tool for crew agents

📖 Copy-paste code for each framework → Integrations docs

📚 Links

• Documentation — Getting Started, CLI Reference, Architecture, FAQ
• Claude Code Plugin — hook details, progressive disclosure, comparison with claude-mem
• OpenClaw — the memory architecture that inspired memsearch
• Milvus — the vector database powering memsearch
• Changelog — release history

Contributing

Bug reports, feature requests, and pull requests are welcome on GitHub. For questions and discussions, join us on Discord.

📄 License

MIT