DOCUMENTATION
A knowledge graph that connects patterns, refactorings, and laws — built for AI agents.
An offline-first software engineering knowledge graph with 100+ canonical entities — design patterns, refactoring techniques, software laws — connected through semantic relationships. Ships as an MCP server for AI agents. Supports code smell detection, ranked refactoring suggestions, and tacit knowledge capture. Single binary, fully offline.
01 · QUICKSTART
Install via cargo. Pre-built binaries also available via cargo-binstall.
# Build from source cargo install episteme # Pre-built binary (faster) cargo binstall episteme
Start the MCP server to give any connected AI agent access to the knowledge graph.
episteme serve
Add Episteme as an MCP server in your Claude Code settings. Once configured, Claude can search patterns, analyze code, and suggest refactorings automatically.
# Add to ~/.claude/settings.json
{
"mcpServers": {
"episteme": {
"command": "episteme",
"args": ["serve"]
}
}
}02 · CORE CONCEPTS
100+ canonical entities spanning design patterns (DP-001 to DP-023), refactoring techniques (RF-001+), software laws (LAW-001+), and code smells (SMELL-001+). Entities are connected through semantic relationships: "solves", "enforces", "violates", "related_to". Traverse the graph to discover non-obvious connections.
9 MCP tools: search_knowledge (hybrid search), analyze_code (smell detection), suggest_refactorings (ranked suggestions), get_entity, get_neighbors, find_path, add_insight (tacit knowledge capture), search_insights, confirm_links. Tools work with any MCP-compatible agent.
analyze_code detects code smells in Python, Java, Go, Rust, TypeScript, C++, C#, Kotlin, PHP, and Ruby. suggest_refactorings returns ranked suggestions using composite scoring: severity + effort + principle alignment + usage frequency.
All 100+ canonical entities ship embedded in the binary. No network calls, no API keys, no cloud dependencies. Tacit knowledge insights are stored locally in SQLite. Works fully offline — on airplanes, in secure environments, anywhere.
03 · REFERENCE
Complete list of MCP tools available to connected agents.
search_knowledge # Hybrid search over knowledge graph analyze_code # Detect code smells in source code suggest_refactorings # Ranked refactoring suggestions get_entity # Get entity details by ID (DP-xxx, LAW-xxx, etc.) get_neighbors # Find related entities via graph edges find_path # Shortest path between two entities add_insight # Capture tacit knowledge from free text search_insights # Search user-contributed insights confirm_links # Validate auto-detected entity links
Core CLI commands for running the server and managing the knowledge base.
episteme serve # Start MCP server (stdio) episteme search "strategy" # Search knowledge graph episteme entity DP-005 # Show entity details episteme path DP-005 SMELL-01 # Find path between entities
04 · CONFIGURATION
Add Episteme to your Claude Code settings to enable knowledge graph tools during coding sessions.
// ~/.claude/settings.json
{
"mcpServers": {
"episteme": {
"command": "episteme",
"args": ["serve"]
}
}
}05 · EXAMPLES
An agent calls analyze_code with source code and gets detected smells, then suggest_refactorings returns ranked fixes.
# Agent: "review this auth module" # → analyze_code detects: Long Method, God Class # → suggest_refactorings returns: # 1. Extract Method (score: 0.92, effort: low) # 2. Replace Conditional with Polymorphism (score: 0.87) # → Agent applies fixes with confidence scores
Search the knowledge graph to discover patterns that solve specific problems, then traverse relationships to find related concepts.
# Agent: "how should I handle multiple algorithms?"
# → search_knowledge("strategy pattern algorithm selection")
# → Returns: Strategy Pattern (DP-005)
# → get_neighbors(DP-005, "solves")
# → Returns: solves State Pattern, related to Open/Closed
# → Agent recommends Strategy + Open/Closed combo