ogm-mcp-skills

MCP Server & AI Agent Skills for OpenGraphMemory and Codebase Knowledge Graphs.

Overview · Tools (29) · Integration Modes · Installation · Quick Setup · Client Configs

MCP stdio server and AI Agent Skills for Google Antigravity, Cursor, Claude Code, OpenCode, Hermes Agent, OpenClaw, and OpenAI Codex to OpenGraphMemory and the Codebase Knowledge Graph.

The MCP server uses authenticated OpenGraphMemory REST APIs only. It is stateless: no local database, session mapping, direct PostgreSQL, Neo4j, or object-store access.

Status

Alpha. PyPI releases are published from GitHub Actions on v* tags. Source install is also supported for development.

Tools

• ogm_health
• ogm_list_datasets
• ogm_search_entities
• ogm_get_entity
• ogm_get_neighbors
• ogm_find_path
• ogm_get_subgraph
• ogm_get_graph
• ogm_get_evidence
• ogm_get_relation_evidence
• ogm_retrieval_query
• ogm_upload_document
• ogm_memory_list_episodes
• ogm_memory_get_episode
• ogm_memory_search
• ogm_memory_create_episode
• ogm_memory_append_attempt
• ogm_memory_record_outcome
• ogm_memory_feedback_episode
• ogm_memory_supersede_episode
• ogm_memory_feedback_pattern
• ogm_memory_supersede_pattern
• ogm_search_code_symbols
• ogm_get_code_call_graph
• ogm_get_code_chunks
• ogm_recall_code_memory
• ogm_record_code_fix
• ogm_sync_code_file
• ogm_index_codebase

Read tools inspect PostgreSQL-authoritative graph and Agent Memory data. Agent Memory results are historical claims: inspect recorded evidence and verifiers before relying on them. personal-safe permits reviewed document upload, additive Agent Memory records, and code sync; memory-curator additionally permits memory feedback and supersession. No delete, admin, project-create, relation-review, analytics-refresh, semantic-retrieval, or automatic conversation-ingestion tools exist.

Install

Install from PyPI with uv:

uv tool install ogm-mcp-skills

Or run without installing:

uvx ogm-mcp-skills==0.2.3 --version

Automated 1-Command Setup

Automatically copy SKILL.md and merge MCP server configuration into your installed agent harness (Antigravity, Gemini CLI, Claude Desktop, Cursor, etc.):

ogm-mcp-skills setup

Or run directly without installing:

uvx ogm-mcp-skills setup

For source development:

git clone https://github.com/ardiannurcahya/ogm-mcp-skills.git "$HOME/src/ogm-mcp-skills"
cd "$HOME/src/ogm-mcp-skills"
uv sync --locked

Integration Modes: On-Demand Skill vs. Always-On Directives

Choose the integration pattern that best fits your workflow:

Enabling Always-On Mode

Copy the directive example matching your AI harness into your workspace root:

• Universal / OpenClaw / Codex: cp examples/AGENTS.md.example AGENTS.md
• Cursor: cp examples/cursor/.cursor/rules/ogm.mdc.example .cursor/rules/ogm.mdc
• Claude Code: cp examples/claude-code/CLAUDE.md.example CLAUDE.md
• Google Antigravity: cp examples/antigravity/GEMINI.md.example GEMINI.md

Configure

Set these environment variables before starting your MCP client:

OGM_BASE_URL=http://localhost:8000
OGM_API_KEY=<project-api-key>
OGM_PROJECT_ID=<project-uuid>
OGM_PERMISSION_PROFILE=read-only

Use OGM_PERMISSION_PROFILE=read-only for graph and Agent Memory retrieval. Use OGM_PERMISSION_PROFILE=personal-safe for reviewed uploads and additive Agent Memory records. Use memory-curator only for reviewed feedback and supersession.

Optional upload roots:

OGM_UPLOAD_ROOTS=/absolute/path/to/allowed/docs

More options: Configuration.

MCP Client Setup

Claude Code

Add MCP server config to project .mcp.json:

{
  "mcpServers": {
    "ogm": {
      "command": "uvx",
      "args": ["ogm-mcp-skills==0.2.3"],
      "env": {
        "OGM_BASE_URL": "${OGM_BASE_URL}",
        "OGM_API_KEY": "${OGM_API_KEY}",
        "OGM_PROJECT_ID": "${OGM_PROJECT_ID}",
        "OGM_PERMISSION_PROFILE": "${OGM_PERMISSION_PROFILE}"
      }
    }
  }
}

Verify:

claude mcp list

OpenCode

Add MCP server config to opencode.json or opencode.jsonc:

{
  "mcp": {
    "ogm": {
      "type": "local",
      "command": ["uvx", "ogm-mcp-skills==0.2.3"],
      "environment": {
        "OGM_BASE_URL": "{env:OGM_BASE_URL}",
        "OGM_API_KEY": "{env:OGM_API_KEY}",
        "OGM_PROJECT_ID": "{env:OGM_PROJECT_ID}",
        "OGM_PERMISSION_PROFILE": "{env:OGM_PERMISSION_PROFILE}"
      },
      "enabled": true
    }
  }
}

Restart OpenCode after editing config.

Hermes

Add server under mcp_servers:

mcp_servers:
  ogm:
    command: "uvx"
    args:
      - "ogm-mcp-skills==0.2.3"
    env:
      OGM_BASE_URL: "${OGM_BASE_URL}"
      OGM_API_KEY: "${OGM_API_KEY}"
      OGM_PROJECT_ID: "${OGM_PROJECT_ID}"
      OGM_PERMISSION_PROFILE: "${OGM_PERMISSION_PROFILE}"
    enabled: true

Verify:

hermes mcp test ogm

For source development, replace uvx ogm-mcp-skills==0.2.1 with:

uv run --project /absolute/path/ogm-mcp-skills ogm-mcp-skills

MCP uses stdio. Diagnostics go to stderr.

Use

After MCP server is connected, ask your agent to use OGM tools. Start with health and dataset discovery:

Call ogm_health, then ogm_list_datasets.

Search entities in one dataset:

{"dataset_id":"dataset-id","q":"OpenGraphMemory","limit":10}

Inspect graph context with ogm_get_entity, ogm_get_neighbors, ogm_get_subgraph, ogm_get_graph, or ogm_find_path. Use ogm_get_relation_evidence or ogm_get_evidence before making evidence-backed claims.

Retrieve relevant operational experience with ogm_memory_search. Create an episode, append attempts, and record a verified outcome only when profile is personal-safe. Feedback and supersession require memory-curator.

Upload documents only when profile is personal-safe and file path is under OGM_UPLOAD_ROOTS:

Call ogm_upload_document with an approved local file path and dataset/project context.

More Docs

• Claude Code
• OpenCode
• Hermes
• Configuration
• Tool schemas

Performance & Token Economics

The MCP server acts as an efficient bridge, converting broad file exploration queries into compact, structured graph and memory payloads:

[!NOTE] Token savings apply to repeated patterns, call-graph explorations, and known incident remediations. Unprecedented architectural problems still require exploratory reasoning, but newly verified solutions are immediately preserved for zero-overhead future retrieval.

Validation

uv sync --dev --locked
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -q
uv build

Security

Use project-scoped keys. Keep .env and keys outside upload roots. Start read-only; use personal-safe only for reviewed writes; reserve memory-curator for memory governance. See security.

License

MIT. See LICENSE.