Hokmah
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Open source Repository Open in the app JSON README (API)
About
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- davidangularme
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Last push
- 2026-04-22T06:41:10Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.davidangularme/hokmah
README
# 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):
```json
{
"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](https://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:
```bash
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`](hokmah-mcp.service).
## Built by
[Catalyst AI Research](https://catalystais.com) · Haifa, Israel
## License
MIT