Hokmah MCP Server

AI Agent with Architectural Memory — MCP Server

Gives any AI coding agent persistent understanding of codebases via TransitionGraph, IdeaGraph, and WorldModel. Analyze impact, generate tests, write code — all from the graph.

<!-- mcp-name: io.github.davidangularme/hokmah -->

Quick Start (30 seconds)

Add to your editor's MCP config (Cursor, Claude Code, VS Code, Windsurf, Cline, JetBrains):

{
  "mcpServers": {
    "hokmah": {
      "type": "streamable-http",
      "url": "https://hokmah.dev/mcp"
    }
  }
}

Then ask your agent: "analyze the impact of refactoring the auth module in github.com/owner/repo"

Available Tools

Tool	Tier	Description
hokmah_analyze	FREE	Impact analysis, risk score, affected files, architectural invariants
hokmah_connect_project	FREE	Connect a GitHub repo, build the architectural graph
hokmah_connect_mcp	FREE	Connect an external MCP server for orchestration
hokmah_generate_tests	PRO	Test generation from the graph (40x fewer tokens)
hokmah_generate_code	PRO	Code generation with architectural memory

How It Works

Hokmah builds a persistent architectural graph from your codebase:

• TransitionGraph — Markov model of code changes (which files change together)
• IdeaGraph — 16 relation types between concepts
• WorldModel — File tree, dependencies, symbols

When you ask "what's the impact of changing X?", Hokmah traverses the graph instead of sending your entire codebase to an LLM. That's why analyze is free (zero LLM tokens) and generate uses 40x fewer tokens.

Pricing

• Free — hokmah_analyze + hokmah_connect_project + hokmah_connect_mcp (unlimited)
• Pro — hokmah_generate_tests + hokmah_generate_code (BYOK — bring your own LLM key)

Get a Pro key at hokmah.dev.

Editor Setup

• Cursor — Settings → MCP → Add server → paste config
• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code — claude mcp add hokmah --transport streamable-http --url https://hokmah.dev/mcp
• VS Code (Copilot) — .vscode/mcp.json in project root
• Windsurf — ~/.windsurf/mcp.json
• Cline — Settings → MCP Servers → Add
• JetBrains — Settings → Tools → AI Assistant → MCP Servers

Self-Hosting

The hosted server at https://hokmah.dev/mcp is the recommended way to use Hokmah. To run the server yourself against your own Hokmah backend:

pip install -r requirements.txt
cp pro_keys.example.json pro_keys.json  # edit with your real PRO keys
HOKMAH_API_BASE=http://localhost:8000 python mcp_server.py

Environment variables:

• HOKMAH_API_BASE — upstream Hokmah API (default http://localhost:8000)
• HOKMAH_MCP_PORT — port to listen on (default 8001)
• HOKMAH_PRO_KEYS — path to the PRO keys JSON file (default /home/vpm/mcp-server/pro_keys.json)

A reference systemd unit is provided in hokmah-mcp.service.

Built by

Catalyst AI Research · Haifa, Israel

License

MIT