Skip to content
Back to search

memsearch-plugins

SkillWorks with CodexGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zilliztech-memsearch/badge.svg)](/listings/zilliztech-memsearch)

HTML

<a href="/listings/zilliztech-memsearch"><img src="/api/listings/zilliztech-memsearch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install as a global CLI tool — recommended when you mainly use the
# `memsearch` command or any of the agent plugins (Claude Code, Codex,
# DSH, OpenClaw, OpenCode, WorkBuddy), which all shell out to the CLI.
uv tool install memsearch       # via uv
pipx install memsearch          # via pipx
pip install memsearch           # plain pip

# Install as a project dependency — use this if you want to import
# `memsearch` from your own Python code (e.g. via the MemSearch class).
uv add memsearch                # via uv, adds to pyproject.toml
pip install memsearch           # into an activated venv

<details> <summary><b>Optional embedding providers</b></summary>

# Install local ONNX support for the CLI
uv tool install "memsearch[onnx]"
pipx install "memsearch[onnx]"
pip install "memsearch[onnx]"

# As a project dependency
uv add "memsearch[onnx]"

# Other options: [openai], [google], [voyage], [jina], [mistral], [ollama], [local], [all]

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines
  1. {
  2. "name": "memsearch-plugins",
  3. "owner": {
  4. "name": "Zilliz",
  5. "email": "support@zilliz.com"
  6. },
  7. "metadata": {
  8. "description": "Semantic memory search plugin for Claude Code — markdown-first, backed by Milvus",
  9. "version": "1.0.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "memsearch",
  14. "description": "Automatic semantic memory for Claude Code — remembers what you worked on across sessions",
  15. "version": "0.4.24",
  16. "source": "./plugins/claude-code",
  17. "category": "productivity",
  18. "author": {
  19. "name": "Zilliz"
  20. },
  21. "homepage": "https://github.com/zilliztech/memsearch",
  22. "repository": "https://github.com/zilliztech/memsearch",
  23. "license": "MIT",
  24. "keywords": ["memory", "semantic-search", "milvus", "markdown"]
  25. }
  26. ]
  27. }
README.md · README · 690 lines · 1 finding marked
  1. <h1 align="center">
  2. <img src="assets/logo-icon.jpg" alt="" width="100" valign="middle">
  3. &nbsp;
  4. memsearch
  5. </h1>
  6. <p align="center">
  7. <strong>Cross-platform semantic memory for AI coding agents.</strong>
  8. </p>
  9. <p align="center">
  10. <a href="https://pypi.org/project/memsearch/"><img src="https://img.shields.io/pypi/v/memsearch?style=flat-square&color=blue" alt="PyPI"></a>
  11. <a href="https://zilliztech.github.io/memsearch/platforms/claude-code/"><img src="https://img.shields.io/badge/Claude_Code-plugin-c97539?style=flat-square&logo=claude&logoColor=white" alt="Claude Code"></a>
  12. <a href="https://zilliztech.github.io/memsearch/platforms/codex/"><img src="https://img.shields.io/badge/Codex-plugin-ff6b35?style=flat-square" alt="Codex"></a>
  13. <a href="https://zilliztech.github.io/memsearch/platforms/dsh/"><img src="https://img.shields.io/badge/DeepSeek_Harness-plugin-4d6bfe?style=flat-square" alt="DeepSeek Harness"></a>
  14. <a href="https://zilliztech.github.io/memsearch/platforms/openclaw/"><img src="https://img.shields.io/badge/OpenClaw-plugin-4a9eff?style=flat-square" alt="OpenClaw"></a>
  15. <a href="https://zilliztech.github.io/memsearch/platforms/opencode/"><img src="https://img.shields.io/badge/OpenCode-plugin-22c55e?style=flat-square" alt="OpenCode"></a>
  16. <a href="https://pypi.org/project/memsearch/"><img src="https://img.shields.io/badge/python-%3E%3D3.10-blue?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
  17. <a href="https://github.com/zilliztech/memsearch/blob/main/LICENSE"><img src="https://img.shields.io/github/license/zilliztech/memsearch?style=flat-square" alt="License"></a>
  18. <a href="https://github.com/zilliztech/memsearch/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/zilliztech/memsearch/test.yml?branch=main&style=flat-square" alt="Tests"></a>
  19. <a href="https://zilliztech.github.io/memsearch/"><img src="https://img.shields.io/badge/docs-memsearch-blue?style=flat-square" alt="Docs"></a>
  20. <a href="https://github.com/zilliztech/memsearch/stargazers"><img src="https://img.shields.io/github/stars/zilliztech/memsearch?style=flat-square" alt="Stars"></a>
  21. <a href="https://discord.com/invite/FG6hMJStWu"><img src="https://img.shields.io/badge/Discord-chat-7289da?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
  22. <a href="https://x.com/zilliz_universe"><img src="https://img.shields.io/badge/follow-%40zilliz__universe-000000?style=flat-square&logo=x&logoColor=white" alt="X (Twitter)"></a>
  23. </p>
  24. <p align="center">
  25. <img src="https://github.com/user-attachments/assets/5d7ea7cd-7a01-471d-9f2d-cff45fd15696" alt="MemSearch saves a memory from Claude Code and recalls it in a later Codex session." width="800">
  26. </p>
  27. ## 📰 What's New
  28. - **Optional Jev reranking** — rerank memory search results with Jev through the TypeSafe API, with no local model download. See [configuration](docs/home/configuration.md#optional-remote-reranking) and the [Chinese/English evaluation](evaluation/reranking-evaluation.md).
  29. - **DeepSeek Harness support** — MemSearch now brings automatic capture, recall hints, native skill-based recall, background maintenance, and a read-only memory browser to [DeepSeek Harness (DSH)](https://zilliztech.github.io/memsearch/platforms/dsh/).
  30. - **Skills from memory** — MemSearch now distills the workflows you repeat into reusable, installable agent skills (a third "procedural memory" layer) and keeps them up to date in the background. See [Skills from Memory](#skills-from-memory).
  31. - **Advanced memory maintenance** — optional background tasks keep durable `PROJECT.md` and `USER.md` notes current across sessions. See [Advanced Memory Maintenance](#advanced-memory-maintenance).
  32. ---
  33. ### Why memsearch?
  34. - 🌐 **All Platforms, One Memory** — memories flow across [Claude Code](plugins/claude-code/README.md), [Codex](plugins/codex/README.md), [DeepSeek Harness](plugins/dsh/README.md), [OpenClaw](plugins/openclaw/README.md), [OpenCode](plugins/opencode/README.md), and [WorkBuddy](docs/platforms/workbuddy.md). A conversation in one agent becomes searchable context in all others — no extra setup
  35. - 👥 **For Agent Users**, install a plugin and get persistent memory with zero effort; **for Agent Developers**, use the full [CLI](https://zilliztech.github.io/memsearch/cli/) and [Python API](https://zilliztech.github.io/memsearch/python-api/) to build memory and harness engineering into your own agents
  36. - 📄 **Markdown is the source of truth** — inspired by [OpenClaw](https://github.com/openclaw/openclaw). Your memories are just `.md` files — human-readable, editable, version-controllable. Milvus is a "shadow index": a derived, rebuildable cache
  37. - 🔍 **Progressive retrieval, hybrid search, smart dedup, live sync** — 3-layer recall (search → expand → transcript); dense vector + BM25 sparse + RRF reranking; SHA-256 content hashing skips unchanged content; file watcher auto-indexes in real time
  38. ---
  39. ## 🧑‍💻 For Agent Users
  40. Choose your agent below for installation and configuration.
  41. <details open>
  42. <summary><h3>For Claude Code Users</h3></summary>
  43. ```bash
  44. # Install
  45. /plugin marketplace add zilliztech/memsearch
  46. /plugin install memsearch
  47. # Restart Claude Code to activate the plugin
  48. ```
  49. After restarting, just chat with Claude Code as usual. The plugin captures every conversation turn automatically.
  50. **Verify it's working** — after a few conversations, check your memory files:
  51. ```bash
  52. ls .memsearch/memory/ # you should see daily .md files
  53. cat .memsearch/memory/$(date +%Y-%m-%d).md
  54. ```
  55. **Recall memories** — two ways to trigger:
  56. ```
  57. /memory-recall what did we discuss about Redis?
  58. ```
  59. Or just ask naturally — Claude auto-invokes the skill when it senses the question needs history:
  60. ```
  61. We discussed Redis caching before, what was the TTL we chose?
  62. ```
  63. > 📖 [Claude Code Plugin docs](https://zilliztech.github.io/memsearch/platforms/claude-code/) · [Troubleshooting](https://zilliztech.github.io/memsearch/platforms/claude-code/troubleshooting/)
  64. </details>
  65. <details open>
  66. <summary><h3>For Codex Users</h3></summary>
  67. ```bash
  68. # Install
  69. git clone --depth 1 https://github.com/zilliztech/memsearch.git
  70. bash memsearch/plugins/codex/scripts/install.sh
  71. codex --yolo # needed for ONNX model network access
  72. ```
  73. After installing, chat as usual. Hooks capture and summarize each turn.
  74. **Verify it's working:**
  75. ```bash
  76. ls .memsearch/memory/
  77. ```
  78. **Recall memories** — use the skill:
  79. ```
  80. $memory-recall what did we discuss about deployment?
  81. ```
  82. > 📖 [Codex Plugin docs](https://zilliztech.github.io/memsearch/platforms/codex/)
  83. </details>
  84. <details open>
  85. <summary><h3>For DeepSeek Harness Users</h3></summary>
  86. ```bash
  87. uv tool install "memsearch[onnx]"
  88. dsh plugin --profile web add @zilliz/memsearch-dsh
  89. ```
  90. For default summaries with an API key saved on DSH's **Models** page, give
  91. `headless` jobs access to saved keys. Add or update this top-level entry in
  92. `~/.dsh/profiles/headless/cordis.patch.yml`, or ask `memory-config` to do it.
  93. ```yaml
  94. - id: credentials
  95. name: '@deepseek-ai/dsh-credentials-local'
  96. disabled: false
  97. ```
  98. Restart your DSH profile or start a new session. Complete a turn, then open
  99. today's file in `.memsearch/memory/` and check for a summary of what you discussed.
  100. **Recall memories** — ask naturally or tell DSH to use the registered `memory-recall` skill:
  101. ```
  102. Use memory-recall to find what we decided about the deployment architecture.
  103. ```
  104. The web profile also adds a compact MemSearch dock where you can review skill candidates and browse supported files under `.memsearch/` without editing them.
  105. > 📖 [DeepSeek Harness Plugin docs](https://zilliztech.github.io/memsearch/platforms/dsh/)
  106. </details>
  107. <details>
  108. <summary><h3>For OpenClaw Users</h3></summary>
  109. ```bash
  110. # Install from ClawHub
  111. openclaw plugins install --force clawhub:memsearch
  112. openclaw config set plugins.entries.memsearch.hooks.allowConversationAccess true
  113. openclaw config set plugins.entries.memsearch.hooks.allowPromptInjection true
  114. openclaw gateway restart
  115. ```
  116. After installing, chat in TUI as usual. The plugin captures each turn automatically.
  117. **Verify it's working** — memory files are stored in your agent's workspace:
  118. ```bash
  119. # For the main agent:
  120. ls ~/.openclaw/workspace/.memsearch/memory/
  121. # For other agents (e.g. work):
  122. ls ~/.openclaw/workspace-work/.memsearch/memory/
  123. ```
  124. **Recall memories** — two ways to trigger:
  125. ```
  126. /memory-recall what was the batch size limit we set?
  127. ```
  128. Or just ask naturally — the LLM auto-invokes memory tools when it senses the question needs history:
  129. ```
  130. We discussed batch size limits before, what did we decide?
  131. ```
  132. > 📖 [OpenClaw Plugin docs](https://zilliztech.github.io/memsearch/platforms/openclaw/) · [Browse on ClawHub](https://clawhub.ai/plugins/memsearch)
  133. </details>
  134. <details>
  135. <summary><h3>For OpenCode Users</h3></summary>
  136. MemSearch gives OpenCode persistent memory across sessions. Install the plugin:
  137. ```bash
  138. opencode plugin add @zilliz/memsearch-opencode
  139. ```
  140. Completed turns are summarized into `.memsearch/memory/` and indexed for recall. Pending work resumes after an interruption.
  141. Ask about previous decisions or debugging sessions, and OpenCode can search memory, expand relevant notes, and look up the original conversation. The `memory-recall`, `memory-config`, and `memory-to-skill` Skills are included.
  142. > 📖 [OpenCode Plugin docs](https://zilliztech.github.io/memsearch/platforms/opencode/)
  143. </details>
  144. <details>
  145. <summary><h3>For WorkBuddy Users</h3></summary>
  146. Follow the [WorkBuddy setup guide](docs/platforms/workbuddy.md) to install the CLI and configure a summary API provider. Then add `zilliztech/memsearch` under **Skills → Kits** and install **memsearch**.
  147. </details>
  148. ### ⚙️ Configuration (all platforms)
  149. All plugins share the same memsearch backend. Configure once, works everywhere.
  150. #### Embedding
  151. Use **ONNX bge-m3** for local CPU embeddings with no API key. On first launch the model (~558 MB) is downloaded from HuggingFace Hub.
  152. ```bash
  153. memsearch config set embedding.provider onnx # local, free
  154. memsearch config set embedding.provider openai # needs OPENAI_API_KEY
  155. memsearch config set embedding.provider ollama # local, any model
  156. ```
  157. > All providers and models: [Configuration — Embedding Provider](https://zilliztech.github.io/memsearch/home/configuration/#embedding-provider)
  158. #### Milvus Backend
  159. Just change `milvus_uri` (and optionally `milvus_token`) to switch between deployment modes:
  160. **Milvus Lite** (default) — zero config, single file. Great for getting started:
  161. ```bash
  162. # Works out of the box, no setup needed
  163. memsearch config get milvus.uri # → ~/.memsearch/milvus.db
  164. ```
  165. ⭐ **Zilliz Cloud** (recommended) — fully managed, [free tier available](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=memsearch-readme) — [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=memsearch-readme) 👇:
  166. ```bash
  167. memsearch config set milvus.uri "https://in03-xxx.api.gcp-us-west1.zillizcloud.com"
  168. memsearch config set milvus.token "your-api-key"
  169. ```
  170. <details>
  171. <summary>⭐ Sign up for a free Zilliz Cloud cluster</summary>
  172. You can [sign up](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=memsearch-readme) on Zilliz Cloud to get a free cluster and API key.
  173. ![Sign up and get API key](https://raw.githubusercontent.com/zilliztech/claude-context/master/assets/signup_and_get_apikey.png)
  174. </details>
  175. <details>
  176. <summary>Self-hosted Milvus Server (Docker) — for advanced users</summary>
  177. For multi-user or team environments with a dedicated Milvus instance. Requires Docker. See the [official installation guide](https://milvus.io/docs/install_standalone-docker-compose.md).
  178. ```bash
  179. memsearch config set milvus.uri http://localhost:19530
  180. ```
  181. </details>
  182. > 📖 Full configuration guide: [Configuration](https://zilliztech.github.io/memsearch/home/configuration/) · [Platform comparison](https://zilliztech.github.io/memsearch/platforms/)
  183. #### Capture Summarization Routing
  184. For agents with a native summarizer, you can override its model:
  185. ```bash
  186. memsearch config set plugins.codex.summarize.model gpt-5.1-codex-mini
  187. memsearch config set plugins.opencode.summarize.model anthropic/claude-haiku
  188. ```
  189. Advanced users can route plugin summarization through a memsearch-managed API provider:
  190. ```bash
  191. memsearch config set llm.providers.openai.type openai
  192. memsearch config set llm.providers.openai.model gpt-5-mini
  193. memsearch config set llm.providers.openai.api_key env:OPENAI_API_KEY
  194. memsearch config set plugins.codex.summarize.provider openai
  195. ```
  196. Leave `plugins.<platform>.summarize.provider` empty to preserve the platform's default behavior. Claude Code, Codex, OpenClaw, and OpenCode also accept `native`; DSH selects its headless-agent backend when the provider is unset. Plugin-specific summarize settings do not fall back to `llm.model`.
  197. You can also disable automatic capture globally for a platform while keeping the plugin installed:
  198. ```bash
  199. memsearch config set plugins.codex.summarize.enabled false
  200. ```
  201. #### Advanced Memory Maintenance
  202. Your agent can keep two higher-level notes current in the background: **`PROJECT.md`** — durable project state (active threads, decisions, risks, next steps) — and **`USER.md`** — your reusable preferences, working style, and recurring goals. They refresh after a session only when the journals changed and a minimum interval has passed, and they are **off by default**.
  203. Turn them on by asking your agent — *"enable MemSearch's PROJECT.md and USER.md maintenance"* — and it configures them through the `memory-config` skill, which can also choose the model/provider, the interval, and custom prompts, or diagnose the current setup. Prefer editing files? The settings live under `[plugins.<agent>.project_review]` and `[plugins.<agent>.user_profile]` in your MemSearch config (both read `.memsearch/memory` and write `.memsearch/PROJECT.md` / `.memsearch/USER.md` by default).
  204. If a background maintenance task seems silent, check `.memsearch/.maintenance-state.json` or ask the `memory-config` skill to inspect it; failed runs record `last_error` and retry on the next due run because failed input digests are not marked successful.
  205. #### Skills from Memory
  206. Beyond the episodic journals and the semantic `PROJECT.md` / `USER.md` notes, MemSearch grows a third memory layer — **procedural memory**: your agent turns the workflows you repeat into reusable, installable skills. You drive it entirely through your agent, in natural language — nothing to memorize:
  207. - *"Make a skill out of what we just did."* — the agent drafts a skill from the session (reading the original transcript so the steps are exact, not guessed), saves it as a candidate, and offers to install it.
  208. - *"What skill candidates do I have? Install the deploy one."* — the agent lists candidates and installs the one you pick into its own skill directory, where it becomes a real `/`-command.
  209. <p align="center">
  210. <img width="1086" height="752" alt="MemSearch skill distillation demo" src="https://github.com/user-attachments/assets/39a90f1c-54e3-4c7a-b168-051f0e096d39">
  211. </p>
  212. Under the hood, candidates live in a git-tracked `.memsearch/skill-candidates/` store — diffable and revertible, and **inert until you install one** (that step is always yours). An optional background pass can also mine recurring workflows from your history on its own. Distilled skills follow the [Agent Skills](https://agentskills.io) open standard, so one capture is portable across Claude Code, Codex, DSH, OpenClaw, OpenCode, and other compatible agents.
  213. **Turning it on is also just a sentence:** ask your agent *"enable MemSearch skill distillation"* (or *"make it more eager"*) and it configures things through the `memory-config` skill — it's off by default. Prefer editing files? The same settings live under `[plugins.<agent>.memory_to_skill]` in your MemSearch config. Full guide: **[Skills from Memory](https://zilliztech.github.io/memsearch/home/skills-from-memory/)**.
  214. ### What can you use it for?
  215. - **Resume debugging threads** — ask how a similar Redis, Docker, database, or deployment issue was fixed last time.
  216. - **Recover decision rationale** — find why the project chose one architecture, library, migration path, or API design over another.
  217. - **Trace feature history** — understand how a feature evolved across sessions, including the files changed and tradeoffs discussed.
  218. - **Do code archaeology** — ask when and why a module, config, or workflow was changed before touching it again.
  219. - **Find the right session to resume** — ask which previous conversation covered a topic, recover the relevant context, and continue from there.
  220. - **Carry context across agents** — keep your agents working from the same project memory.
  221. ---
  222. ## 🛠️ For Agent Developers
  223. Beyond ready-to-use plugins, memsearch provides a complete **CLI and Python API** for building memory into your own agents. Whether you're adding persistent context to a custom agent, building a memory-augmented RAG pipeline, or doing harness engineering — the same core engine that powers the plugins is available as a library.
  224. ### 🏗️ Architecture Overview
  225. ```
  226. ┌──────────────────────────────────────────────────────────────┐
  227. │ 🧑‍💻 For Agent Users (Plugins) │
  228. │ Claude Code · Codex · DSH · OpenClaw · OpenCode · WorkBuddy │
  229. │ │ │
  230. ├────────────────────────────┬─────────────────────────────────┤
  231. │ 🛠️ For Agent Developers │ Build your own with ↓ │
  232. │ ┌─────────────────────────┴──────────────────────────────┐ │
  233. │ │ memsearch CLI / Python API │ │
  234. │ │ index · search · expand · watch · compact │ │
  235. │ └─────────────────────────┬──────────────────────────────┘ │
  236. │ ┌─────────────────────────┴──────────────────────────────┐ │
  237. │ │ Core: Chunker → Embedder → Milvus │ │
  238. │ │ Hybrid Search (BM25 + Dense + RRF) │ │
  239. │ └────────────────────────────────────────────────────────┘ │
  240. ├──────────────────────────────────────────────────────────────┤
  241. │ 📄 Markdown Files (Source of Truth) │
  242. │ memory/2026-03-27.md · memory/2026-03-26.md · ... │
  243. └──────────────────────────────────────────────────────────────┘
  244. ```
  245. Plugins sit on top of the CLI/API layer. The API handles indexing, searching, and Milvus sync. Markdown files are always the source of truth — Milvus is a rebuildable shadow index. Everything below the plugin layer is what you use as an agent developer.
  246. ### How Plugins Work (Claude Code as example)
  247. **Capture — after each conversation turn:**
  248. ```
  249. User asks question → Agent responds → Stop hook fires
  250. │
  251. ┌────────────────────┘
  252. ▼
  253. Parse last turn
  254. │
  255. ▼
  256. LLM summarizes (haiku)
  257. "- User asked about X."
  258. "- Claude did Y."
  259. │
  260. ▼
  261. Append to memory/2026-03-27.md
  262. with <!-- session:UUID --> anchor
  263. │
  264. ▼
  265. memsearch index → Milvus
  266. ```
  267. **Recall — 3-layer progressive search:**
  268. ```
  269. User: "What did we discuss about batch size?"
  270. │
  271. ▼
  272. L1 memsearch search "batch size" → ranked chunks
  273. │ (need more?)
  274. ▼
  275. L2 memsearch expand <chunk_hash> → full .md section
  276. │ (need original?)
  277. ▼
  278. L3 parse-transcript <session.jsonl> → raw dialogue
  279. ```
  280. ### 📄 Markdown as Source of Truth
  281. ```
  282. Plugins append ──→ .md files ←── human editable
  283. │
  284. ▼
  285. memsearch watch (live watcher)
  286. │
  287. detects file change
  288. │
  289. ▼
  290. re-chunk changed .md
  291. │
  292. hash each chunk (SHA-256)
  293. │
  294. ┌───────────┴───────────┐
  295. ▼ ▼
  296. hash unchanged? hash is new/changed?
  297. → skip (no API call) → embed → upsert to Milvus
  298. │ │
  299. └───────────┬───────────┘
  300. ▼
  301. ┌──────────────────┐
  302. │ Milvus (shadow) │
  303. │ always in sync │
  304. │ rebuildable │
  305. └──────────────────┘
  306. ```
  307. ### 📦 Installation
  308. ```bash
  309. # Install as a global CLI tool — recommended when you mainly use the
  310. # `memsearch` command or any of the agent plugins (Claude Code, Codex,
  311. # DSH, OpenClaw, OpenCode, WorkBuddy), which all shell out to the CLI.
  312. uv tool install memsearch # via uv
  313. pipx install memsearch # via pipx
  314. pip install memsearch # plain pip
  315. # Install as a project dependency — use this if you want to import
  316. # `memsearch` from your own Python code (e.g. via the MemSearch class).
  317. uv add memsearch # via uv, adds to pyproject.toml
  318. pip install memsearch # into an activated venv
  319. ```
  320. <details>
  321. <summary><b>Optional embedding providers</b></summary>
  322. ```bash
  323. # Install local ONNX support for the CLI
  324. uv tool install "memsearch[onnx]"
  325. pipx install "memsearch[onnx]"
  326. pip install "memsearch[onnx]"
  327. # As a project dependency
  328. uv add "memsearch[onnx]"
  329. # Other options: [openai], [google], [voyage], [jina], [mistral], [ollama], [local], [all]
  330. ```
  331. </details>
  332. ### 🐍 Python API — Give Your Agent Memory
  333. The Python API defaults to OpenAI (`OPENAI_API_KEY`). For local embeddings, pass `embedding_provider="onnx"`.
  334. ```python
  335. from memsearch import MemSearch
  336. mem = MemSearch(paths=["./memory"])
  337. await mem.index() # index markdown files
  338. results = await mem.search("Redis config", top_k=3) # semantic search
  339. scoped = await mem.search("pricing", top_k=3, source_prefix="./memory/product")
  340. print(results[0]["content"], results[0]["score"]) # content + similarity
  341. ```
  342. <details>
  343. <summary><b>Full example — agent with memory (OpenAI)</b> — click to expand</summary>
  344. ```python
  345. import asyncio
  346. from datetime import date
  347. from pathlib import Path
  348. from openai import OpenAI
  349. from memsearch import MemSearch
  350. MEMORY_DIR = "./memory"
  351. llm = OpenAI() # your LLM client
  352. mem = MemSearch(paths=[MEMORY_DIR]) # memsearch handles the rest
  353. def save_memory(content: str):
  354. """Append a note to today's memory log (OpenClaw-style daily markdown)."""
  355. p = Path(MEMORY_DIR) / f"{date.today()}.md"
  356. p.parent.mkdir(parents=True, exist_ok=True)
  357. with open(p, "a") as f:
  358. f.write(f"\n{content}\n")
  359. async def agent_chat(user_input: str) -> str:
  360. # 1. Recall — search past memories for relevant context
  361. memories = await mem.search(user_input, top_k=3)
  362. context = "\n".join(f"- {m['content'][:200]}" for m in memories)
  363. # 2. Think — call LLM with memory context
  364. resp = llm.chat.completions.create(
  365. model="gpt-5-mini",
  366. messages=[
  367. {"role": "system", "content": f"You have these memories:\n{context}"},
  368. {"role": "user", "content": user_input},
  369. ],
  370. )
  371. answer = resp.choices[0].message.content
  372. # 3. Remember — save this exchange and index it
  373. save_memory(f"## {user_input}\n{answer}")
  374. await mem.index()
  375. return answer
  376. async def main():
  377. # Seed some knowledge
  378. save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
  379. save_memory("## Decision\nWe chose Redis for caching over Memcached.")
  380. await mem.index() # or mem.watch() to auto-index in the background
  381. # Agent can now recall those memories
  382. print(await agent_chat("Who is our frontend lead?"))
  383. print(await agent_chat("What caching solution did we pick?"))
  384. asyncio.run(main())
  385. ```
  386. </details>
  387. <details>
  388. <summary><b>Anthropic Claude example</b> — click to expand</summary>
  389. ```bash
  390. pip install memsearch anthropic
  391. ```
  392. ```python
  393. import asyncio
  394. from datetime import date
  395. from pathlib import Path
  396. from anthropic import Anthropic
  397. from memsearch import MemSearch
  398. MEMORY_DIR = "./memory"
  399. llm = Anthropic()
  400. mem = MemSearch(paths=[MEMORY_DIR])
  401. def save_memory(content: str):
  402. p = Path(MEMORY_DIR) / f"{date.today()}.md"
  403. p.parent.mkdir(parents=True, exist_ok=True)
  404. with open(p, "a") as f:
  405. f.write(f"\n{content}\n")
  406. async def agent_chat(user_input: str) -> str:
  407. # 1. Recall
  408. memories = await mem.search(user_input, top_k=3)
  409. context = "\n".join(f"- {m['content'][:200]}" for m in memories)
  410. # 2. Think — call Claude with memory context
  411. resp = llm.messages.create(
  412. model="claude-sonnet-4-6",
  413. max_tokens=1024,
  414. system=f"You have these memories:\n{context}",
  415. messages=[{"role": "user", "content": user_input}],
  416. )
  417. answer = resp.content[0].text
  418. # 3. Remember
  419. save_memory(f"## {user_input}\n{answer}")
  420. await mem.index()
  421. return answer
  422. async def main():
  423. save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
  424. await mem.index()
  425. print(await agent_chat("Who is our frontend lead?"))
  426. asyncio.run(main())
  427. ```
  428. </details>
  429. <details>
  430. <summary><b>Ollama (fully local, no API key)</b> — click to expand</summary>
  431. ```bash
  432. pip install "memsearch[ollama]"
  433. ollama pull nomic-embed-text # embedding model
  434. ollama pull llama3.2 # chat model
  435. ```
  436. ```python
  437. import asyncio
  438. from datetime import date
  439. from pathlib import Path
  440. from ollama import chat
  441. from memsearch import MemSearch
  442. MEMORY_DIR = "./memory"
  443. mem = MemSearch(paths=[MEMORY_DIR], embedding_provider="ollama")
  444. def save_memory(content: str):
  445. p = Path(MEMORY_DIR) / f"{date.today()}.md"
  446. p.parent.mkdir(parents=True, exist_ok=True)
  447. with open(p, "a") as f:
  448. f.write(f"\n{content}\n")
  449. async def agent_chat(user_input: str) -> str:
  450. # 1. Recall
  451. memories = await mem.search(user_input, top_k=3)
  452. context = "\n".join(f"- {m['content'][:200]}" for m in memories)
  453. # 2. Think — call Ollama locally
  454. resp = chat(
  455. model="llama3.2",
  456. messages=[
  457. {"role": "system", "content": f"You have these memories:\n{context}"},
  458. {"role": "user", "content": user_input},
  459. ],
  460. )
  461. answer = resp.message.content
  462. # 3. Remember
  463. save_memory(f"## {user_input}\n{answer}")
  464. await mem.index()
  465. return answer
  466. async def main():
  467. save_memory("## Team\n- Alice: frontend lead\n- Bob: backend lead")
  468. await mem.index()
  469. print(await agent_chat("Who is our frontend lead?"))
  470. asyncio.run(main())
  471. ```
  472. </details>
  473. > 📖 Full Python API reference: [Python API docs](https://zilliztech.github.io/memsearch/python-api/)
  474. ### ⌨️ CLI Usage
  475. **Setup:**
  476. ```bash
  477. memsearch config init # interactive setup wizard
  478. memsearch config set embedding.provider onnx # switch embedding provider
  479. memsearch config set milvus.uri http://localhost:19530 # switch Milvus backend
  480. ```
  481. **Index & Search:**
  482. ```bash
  483. memsearch index ./memory/ # index markdown files
  484. memsearch index ./memory/ ./notes/ --force # re-embed everything
  485. memsearch index . --ignore-file .gitignore # opt in to repository ignore rules
  486. memsearch search "Redis caching" # hybrid search (BM25 + vector)
  487. memsearch search "auth flow" --top-k 10 --json-output # JSON for scripting
  488. memsearch expand <chunk_hash> # show full section around a chunk
  489. ```
  490. **Live Sync & Maintenance:**
  491. ```bash
  492. memsearch watch ./memory/ # live file watcher (auto-index on change)
  493. memsearch compact # LLM-powered chunk summarization
  494. memsearch stats # show indexed chunk count
  495. memsearch reset --yes # drop all indexed data and rebuild
  496. ```
  497. > 📖 Full CLI reference with all flags: [CLI docs](https://zilliztech.github.io/memsearch/cli/)
  498. ## ⚙️ Configuration
  499. Embedding and Milvus backend settings → [Configuration (all platforms)](#️-configuration-all-platforms)
  500. Collection priority: integration-derived default → `~/.memsearch/config.toml` → `.memsearch.toml` → explicit `--collection` or Python argument. Without an integration-derived default, the built-in collection is used.
  501. > 📖 Full config guide: [Configuration](https://zilliztech.github.io/memsearch/home/configuration/)
  502. ## 🔗 Links
  503. - 📖 [Documentation](https://zilliztech.github.io/memsearch/) — full guides, API reference, and architecture details
  504. - 🔌 [Platform Plugins](https://zilliztech.github.io/memsearch/platforms/) — Claude Code, Codex, DeepSeek Harness, OpenClaw, OpenCode, WorkBuddy
  505. - 💡 [Design Philosophy](https://zilliztech.github.io/memsearch/design-philosophy/) — why markdown, why Milvus, competitor comparison
  506. - 🦞 [OpenClaw](https://github.com/openclaw/openclaw) — the memory architecture that inspired memsearch
  507. - 🗄️ [Milvus](https://milvus.io/) | [Zilliz Cloud](https://cloud.zilliz.com/signup?utm_source=github&utm_medium=referral&utm_campaign=memsearch-readme) — the vector database powering memsearch
  508. ## 🤝 Contributing
  509. Bug reports, feature requests, and pull requests are welcome! See the [Contributing Guide](CONTRIBUTING.md) for development setup, testing, and plugin development instructions. For questions and discussions, join us on [Discord](https://discord.com/invite/FG6hMJStWu).
  510. ## 📄 License
  511. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.