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: exocortex

Tools

search_memory result fields

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

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,<4

• 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