oG-Memory RAG MCP

An MCP server that gives any agent a search_kb tool over a remote oG-Memory knowledge base.

Install this MCP, set two environment variables — OGMEM_API_URL and OGMEM_API_TOKEN — and your agent can query the shared knowledge base directly. No local oG-Memory install, no vector DB, nothing else. The knowledge base runs on a server; this is just the thin client that connects your agent to it.

agent (Claude Code / Cursor / VS Code / …)
  └─ ogmem-rag-mcp  ──HTTP──►  oG-Memory server  (search_kb, token-gated)
        tool: search_kb            └─ vector + BM25 retrieval over the KB

Requirements

• uv on PATH (provides uvx). Nothing else — uvx fetches and runs the server on demand.
• An oG-Memory KB server URL and its team token (ask your admin).

Configuration (the only two you must set)

Variable	Required	Meaning
OGMEM_API_URL	✅	The KB server, e.g. http://110.40.165.184:19532
OGMEM_API_TOKEN	✅ for shared servers	Team token, sent as the X-KB-Token header
OGMEM_ACCOUNT_ID	optional	KB account (default compatibility-sdk-5.1.1)
OGMEM_USER_ID	optional	Caller id recorded in retrieval signals
OGMEM_TIMEOUT	optional	Per-request seconds (default 60)

---

Install

Every host uses the same command — uvx ogmem-rag-mcp — with the two env vars. Pick your host below.

Cursor

Click the button (then replace <team-token> in the installed entry), or add to ~/.cursor/mcp.json manually:

{
  "mcpServers": {
    "ogmem-rag": {
      "command": "uvx",
      "args": ["ogmem-rag-mcp"],
      "env": {
        "OGMEM_API_URL": "http://110.40.165.184:19532",
        "OGMEM_API_TOKEN": "<team-token>"
      }
    }
  }
}

Claude Code

One line:

claude mcp add ogmem-rag \
  --env OGMEM_API_URL=http://110.40.165.184:19532 \
  --env OGMEM_API_TOKEN=<team-token> \
  -- uvx ogmem-rag-mcp

VS Code

Or add to .vscode/mcp.json:

{
  "servers": {
    "ogmem-rag": {
      "command": "uvx",
      "args": ["ogmem-rag-mcp"],
      "env": {
        "OGMEM_API_URL": "http://110.40.165.184:19532",
        "OGMEM_API_TOKEN": "<team-token>"
      }
    }
  }
}

Claude Desktop / Windsurf / Cline / Zed / any other MCP host

Same server entry in the host's MCP config file:

{
  "mcpServers": {
    "ogmem-rag": {
      "command": "uvx",
      "args": ["ogmem-rag-mcp"],
      "env": {
        "OGMEM_API_URL": "http://110.40.165.184:19532",
        "OGMEM_API_TOKEN": "<team-token>"
      }
    }
  }
}

Before it's on PyPI, replace "args": ["ogmem-rag-mcp"] with "args": ["--from", "git+https://github.com/PoivronMax/oG-Memory-RAG", "ogmem-rag-mcp"] to run straight from GitHub.

---

Usage — how you actually query the KB

You don't run any command. Once the MCP is installed in your host, just talk to your agent normally. The agent sees a search_kb tool and calls it on its own whenever your question looks like something the knowledge base can answer — then answers you using what it found. The "query" is phrased by the agent, not typed by you.

You:   "In Cangjie, how do I measure text width before drawing on a Canvas?"
Agent: (decides the KB can help) → calls search_kb("Canvas measureText text width")
       → gets the measureText signature back → writes the code for you.

Nothing to memorize, no special syntax — your normal chat is the interface.

Want to force it (when the agent didn't search but you think it should)? Just say so in plain language:

"Search the KB for how to set a TextInput placeholder."
"Check the knowledge base for Cangjie's match expression syntax first, then write it."
"Use search_kb to look up AbilityStage lifecycle callbacks."

Any phrasing that mentions the KB / knowledge base / search_kb nudges the agent to call the tool. It's still natural language — you're just pointing at it.

This is an MCP tool for the agent, not a search box for you. There is no UI; the chat window is the interface, and the agent decides when and what to search. It won't query the KB for unrelated questions.

Verify the connection (one-time, optional)

This is a health probe you run once to confirm the URL + token work — it is not how you query day-to-day (that's the Usage section above). You never need to type OGMEM_... on the command line again after this.

OGMEM_API_URL=http://110.40.165.184:19532 OGMEM_API_TOKEN=<team-token> \
  uvx ogmem-rag-mcp --check
# -> {"base_url": "...", "account_id": "compatibility-sdk-5.1.1", "health": {"status": "ok", ...}}

status: ok → ready, go chat with your agent. 403 → missing/wrong token. Connection error → OGMEM_API_URL unreachable (check the address / your network).

The tool the agent gets

search_kb(query, top_k=8, snippet_chars=1500, min_score=None, categories=None) — searches the KB and returns ranked hits. Each hit carries uri (source/provenance), score, category, abstract, and a query-centered snippet (with a truncated flag). Results are precise excerpts, not whole-document dumps. When a hit looks right but its snippet is truncated, search again with that document's distinctive terms and a larger snippet_chars (up to 20000) to read deeper.

How it talks to the server

• Calls only POST /api/v1/call/search_kb (retrieval) and GET /api/v1/health (probe) — both read-only and whitelisted on the server's reverse proxy. No write path is exposed.
• Sends the token as X-KB-Token; ignores system proxy env vars so a corporate/local proxy won't hijack the direct call.
• Stateless: every call is independent; nothing is created on the server.

Develop

uv venv && uv pip install -e ".[dev]"
pytest            # unit tests use httpx MockTransport, no live server needed

Publishing (maintainers)

Releases go to PyPI via Trusted Publishing (OIDC — no stored token). One-time:

1. On PyPI, add a pending trusted publisher: project ogmem-rag-mcp, owner PoivronMax, repo oG-Memory-RAG, workflow publish.yml, environment pypi.
2. In the GitHub repo settings, create an environment named pypi.

Then each release is just:

# bump version in pyproject.toml + src/ogmem_rag_mcp/__init__.py, commit, then:
git tag v0.1.0 && git push origin v0.1.0

The publish.yml workflow builds and uploads automatically.

Relationship to oG-Memory

The server side (ingestion, chunking, embedding, the search_kb endpoint) lives in oG-Memory. This repo is only the MCP client surface, kept standalone so it installs anywhere without pulling in the full engine.