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.

Tools

Tool	Description	Key Parameters	Returns
search_memory	Hybrid vector+BM25+reranker search over Milvus-indexed agent memory	query: str, limit: int = 10	list[dict] — results sorted by score
index_memory	Trigger a memsearch index refresh for a path or default to ~/.claude/memory/	path: str | None	{"indexed": N, "path": str}

search_memory result fields

Field	Type	Description
path	str	Absolute path to the source file
score	float	Relevance score (higher = more relevant)
snippet	str	Matching text chunk
heading	str | null	Nearest markdown heading above the chunk
tier	str	session, working, docs, or unknown
start_line	int	First line of the chunk in the source file
end_line	int	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
MEMSEARCH_MCP_PORT	No	8493	Port for the streamable-http server
MEMSEARCH_API_TOKEN	No	(none)	Bearer token for HTTP authentication. When set, all requests must include Authorization: Bearer <token>. Uses hmac.compare_digest() for constant-time comparison. Disabled when unset.
LOG_LEVEL	No	INFO	structlog log level
MEMSEARCH_CONFIG	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>=2.0
• pydantic>=2.0
• structlog>=24.0
• memsearch (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 save

scoped-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 sysadmin

The 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 -5