memsearch-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
memsearch-mcp
FastMCP server wrapping the memsearch semantic memory search library. Exposes hybrid vector+BM25+reranker search and index-refresh tools to forge agents over streamable-http MCP transport.
Overview
Agent memory on forge lives in markdown files across a three-tier hierarchy: session (per-project
plugin dirs), working (~/.claude/memory/), and docs. memsearch-mcp lets agents query all of
it with a single tool call — without reading files directly or knowing where they live.
Who uses it: All 5 forge resident agents (research, developer, writer, security, sysadmin)
have memsearch-mcp in their scoped-mcp manifests. index_memory is denylisted for security,
research, and writer.
Related MCP server: Keepygaga RAG
Tools
Tool | Description | Key Parameters | Returns |
| Hybrid vector+BM25+reranker search over Milvus-indexed agent memory |
|
|
| Trigger a memsearch index refresh for a path or default to |
|
|
search_memory result fields
Field | Type | Description |
|
| Absolute path to the source file |
|
| Relevance score (higher = more relevant) |
|
| Matching text chunk |
|
| Nearest markdown heading above the chunk |
|
|
|
|
| First line of the chunk in the source file |
|
| Last line of the chunk |
index_memory path restrictions
index_memory accepts only paths under:
~/.claude/memory/~/.claude/projects//opt/agents/memory/
Requests outside these roots are rejected with an error (not forwarded to the library).
Environment Variables
Variable | Required | Default | Purpose |
| No |
| Port for the streamable-http server |
| No | (none) | Bearer token for HTTP authentication. When set, all requests must include |
| No |
| structlog log level |
| No | (library default) | Path to memsearch config file |
Installation
Requires Python 3.11+ and an existing memsearch venv with the memsearch library installed.
# From the memsearch venv (forge standard)
/opt/venvs/memsearch/bin/pip install -e /home/ted/repos/personal/memsearch-mcp
# Or from git
/opt/venvs/memsearch/bin/pip install "git+https://github.com/TadMSTR/memsearch-mcp.git"Dependencies
fastmcp>=3.2.4,<4pydantic>=2.0structlog>=24.0memsearch(must be installed in the same venv — not in PyPI, install from source)
Deployment
PM2
ecosystem.config.js in the repo root:
module.exports = {
apps: [{
name: "memsearch-mcp",
script: "/opt/venvs/memsearch/bin/python3",
args: ["-m", "memsearch_mcp.server"],
cwd: "/home/ted/repos/personal/memsearch-mcp",
interpreter: "none",
env: {
LOG_LEVEL: "INFO",
MEMSEARCH_MCP_PORT: "8493",
},
}]
};pm2 start ecosystem.config.js
pm2 savescoped-mcp wiring
Add to each agent manifest at ~/.claude/manifests/<agent>-agent.yml:
modules:
memsearch-mcp:
type: mcp_proxy
config:
url: http://127.0.0.1:8493/mcp
headers:
Authorization: "Bearer ${MEMSEARCH_API_TOKEN}"
tool_denylist:
- "index_memory" # omit for developer and sysadminThe headers config injects an Authorization header into every upstream request via
scoped-mcp's mcp_proxy module. ${MEMSEARCH_API_TOKEN} is resolved from the agent's
Vault-backed credentials at session start — agents never see the token value.
No restart of scoped-mcp is needed — manifests are loaded fresh on each agent session start.
Observability
Logs are written to ~/logs/memsearch-mcp.log (stdout + stderr merged, timestamped by PM2).
Log lines are JSON (structlog):
{"event": "search_memory", "query": "grafana dashboard", "limit": 10, "level": "info"}
{"event": "search_memory_done", "query": "grafana dashboard", "results": 7, "level": "info"}
{"event": "index_memory_dir_done", "path": "/home/ted/.claude/memory", "chunks": 412, "level": "info"}Tool arguments are not included in logs — only query strings and result counts.
To check server health:
pm2 status memsearch-mcp
# Without auth (should return 401 when MEMSEARCH_API_TOKEN is set)
curl -s http://127.0.0.1:8493/mcp
# With auth
curl -s -H "Authorization: Bearer $MEMSEARCH_API_TOKEN" http://127.0.0.1:8493/mcp | head -5Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Shared Markdown memory for your agents: docs, typed collections, files, skills and Dispatch.
Persistent memory for AI agents. Search, store, and recall across sessions.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables coding agents to query local notes, decisions, docs, and code with hybrid retrieval (BM25 + embeddings + reranking) and get path:line citations. It provides tools like rag_query for full-corpus search and search_knowledge for project-scoped knowledge recall.21MIT
- AlicenseAqualityCmaintenanceEnables local-first hybrid knowledge retrieval from authorized Markdown and plain-text files, combining full-text and vector search with reranking and traceable source references via a single search tool.1MIT
- AlicenseNot gradedqualityBmaintenanceProvides hybrid search (BM25 + vector) and staleness reporting for local markdown notes, exposing search and indexing tools to AI assistants via MCP.7 npmMIT
- AlicenseNot gradedqualityDmaintenanceProvides coding agents with persistent local memory by exposing tools to save, search, and retrieve decisions, bugs, and context as Markdown with hybrid keyword and semantic search.4MIT