memory-lancedb-pro-mcp

MCP server that exposes memory-lancedb-pro as durable semantic memory tools for Hermes Agent and other MCP clients.

This repo is intentionally a bridge, not a Hermes fork and not an OpenClaw plugin. It keeps the MCP surface small while using the memory-lancedb-pro storage, embedding, and retrieval primitives underneath.

Status

Early scaffold:

• stdio MCP server
• memory_store
• memory_search
• memory_recall_context
• memory_list
• memory_delete
• memory_stats
• pinned public memory-lancedb-pro GitHub tarball dependency for the first development pass

Install

Prerequisites:

• Node.js 22 or newer
• npm

npm install
npm run build

The first scaffold pins memory-lancedb-pro to a known GitHub tarball while the reusable core boundary settles.

Verification

Run the local deterministic checks:

npm run build
npm test
npm run typecheck
npm run smoke

The smoke suite uses a local fake OpenAI-compatible embedding endpoint, so it does not need a real embedding API key and does not send memory text to an external service.

Ubuntu's default apt install nodejs npm may install Node 20, which is below this repo's Node 22+ requirement. Use NodeSource, Homebrew, nvm, or another current Node distribution when needed.

Configuration

The server reads configuration from environment variables.

Required:

export MEMORY_EMBEDDING_API_KEY="..."

Common options:

export MEMORY_DB_PATH="$HOME/.hermes/memory-lancedb-pro-mcp"
export MEMORY_DEFAULT_SCOPE="global"
export MEMORY_EMBEDDING_MODEL="text-embedding-3-small"
export MEMORY_EMBEDDING_BASE_URL="https://api.openai.com/v1"
export MEMORY_EMBEDDING_DIMENSIONS="1536"
export MEMORY_RETRIEVAL_MODE="hybrid"
export MEMORY_RERANK="none"

For OpenAI-compatible local providers, set MEMORY_EMBEDDING_BASE_URL, MEMORY_EMBEDDING_MODEL, and MEMORY_EMBEDDING_DIMENSIONS.

Hermes Agent

Add the built server to ~/.hermes/config.yaml:

mcp_servers:
  lancedb_memory:
    command: "node"
    args: ["/path/to/memory-lancedb-pro-mcp/dist/server.js"]
    env:
      MEMORY_EMBEDDING_API_KEY: "${OPENAI_API_KEY}"
      MEMORY_DB_PATH: "${HOME}/.hermes/memory-lancedb-pro-mcp"
      MEMORY_EMBEDDING_MODEL: "text-embedding-3-small"
      MEMORY_RETRIEVAL_MODE: "hybrid"
      MEMORY_RERANK: "none"
    timeout: 120

Hermes will register these as MCP tools with its configured MCP prefix. This does not replace Hermes built-in MEMORY.md and USER.md; it adds a deeper semantic memory tool layer.

You can also add and verify it with the Hermes CLI:

hermes mcp add memory_lancedb_pro \
  --command node \
  --env MEMORY_EMBEDDING_API_KEY="$OPENAI_API_KEY" MEMORY_DB_PATH="$HOME/.hermes/memory-lancedb-pro-mcp" MEMORY_RERANK=none \
  --args "$PWD/dist/server.js"

hermes mcp list
hermes mcp test memory_lancedb_pro

hermes mcp test memory_lancedb_pro should report six discovered tools.

Tool Shape

memory_store

{
  "text": "User prefers TypeScript for new Node projects.",
  "category": "preference",
  "scope": "user:local",
  "importance": 0.8,
  "metadata": { "source": "manual" }
}

memory_search

{
  "query": "What does the user prefer for Node projects?",
  "scopes": ["global", "user:local"],
  "limit": 5
}

memory_recall_context returns a compact prompt-ready block:

<relevant-memories>
- [id] (preference, user:local, importance=0.8, score=0.912, 2026-01-01T00:00:00.000Z) User prefers TypeScript for new Node projects.
</relevant-memories>

Design Notes

This repo starts with MCP tools because Hermes cannot directly run OpenClaw typed hooks such as before_prompt_build and agent_end. A future Hermes-native memory provider could add automatic prefetch, turn sync, and session-end extraction. The MCP server is the smaller useful slice.

Next likely pieces:

• package memory-lancedb-pro reusable core cleanly instead of importing dist/src/*
• add import/export tools for Hermes session search results
• add optional auto-capture helper prompts or a Hermes skill
• publish a Docker image or npm package after the adapter boundary stabilizes