GitHub - epicsagas/Episteme: A production-ready knowledge graph system for software engineering that connects design patterns, refactoring techniques, and software laws through semantic relationships. Built for AI agents first — integrate software engineering expertise directly into Claude Code, Cursor, and other MCP-compatible tools.

_{Episteme (ἐπιστήμη) — Greek for "systematic knowledge, scientific understanding"}

An offline-first, single-binary knowledge graph that connects design patterns, refactoring techniques, and software laws through semantic relationships.
Built for AI agents first — integrate software engineering expertise directly into Claude Code, Cursor, and other MCP-compatible tools.

Written in Rust · Single binary · Fully offline

Quick Start

Claude Code

/plugin marketplace add epicsagas/plugins
/plugin install episteme@epicsagas

The plugin hook installs the epis binary automatically. Before starting a new session, run this once in your terminal:

epis install   # download knowledge graph data from GitHub Releases

epis install seeds the knowledge graph database and starts the HTTP API server on port 58302. Then start a new Claude Code session and you're done.

Updates with /plugin update episteme@epicsagas.

Codex CLI

codex plugin marketplace add epicsagas/plugins

The plugin hook installs the epis binary automatically. Before starting a new session, run this once in your terminal:

epis install   # download knowledge graph data from GitHub Releases

epis install seeds the knowledge graph database and starts the HTTP API server on port 58302. Updates with codex plugin update episteme@epicsagas.

Other tools

epis install cursor       # Cursor IDE
epis install opencode     # OpenCode
epis install cline        # Cline
epis install --all        # All supported tools

Manual install

Method	Command
Homebrew	`brew install epicsagas/tap/episteme`
Shell script	`curl --proto '=https' --tlsv1.2 -LsSf https://github.com/epicsagas/Episteme/releases/latest/download/episteme-installer.sh \| sh`
PowerShell	`irm https://github.com/epicsagas/Episteme/releases/latest/download/episteme-installer.ps1 \| iex`
cargo	`cargo binstall episteme` ⚡ or `cargo install episteme`
Docker	See Option 3

Verify

epis --version
epis stats

Or from inside Claude Code / Codex CLI:

/episteme verify

Try it in 30 seconds

Option A — CLI: Point it at any file in your project.

epis analyze src/domain/engine.rs

✓ 2 smells detected in src/domain/engine.rs

  SMELL-07 (Large Class) — RefactoringRanker, 743 lines
  → RF-018 Extract Class          priority 0.89  effort: medium
  → RF-001 Extract Method         priority 0.76  effort: small
  → Violates: LAW-001 Single Responsibility Principle

  SMELL-01 (Long Method) — rank_refactorings(), 58 lines
  → RF-001 Extract Method         priority 0.92  effort: small
  → Violates: LAW-001 SRP, LAW-004 DRY

Option B — Claude Code: Open any file in your project and ask naturally.

Find code smells in this project and suggest refactorings.

Episteme auto-triggers — no special syntax needed. It maps your description to the knowledge graph and returns ranked, citable results.

Why Episteme?

LLMs already know what the Strategy pattern is. They can recite SOLID principles, list GoF patterns, and explain code smells. So why does this project exist?

The gap isn't knowledge — it's structured, connected reasoning.

When you ask an LLM "how do I fix a God Object?", it gives you a reasonable answer. But the answer changes between conversations, lacks traceability, and doesn't connect the problem to its root causes or downstream consequences. Episteme turns isolated facts into a traversable graph where every recommendation is grounded, citable, and connected to the broader design landscape.

How is this different from just prompting an LLM well?

	Well-crafted LLM prompt	Episteme + LLM
Proactive detection	Only if the user asks the right question	Auto-triggers on problem descriptions
Token efficiency	Long explanations + multiple follow-up turns	One tool call returns structured result
Relationship traversal	One-hop at best, often hallucinated	Multi-hop graph traversal, verified
Cross-referencing	Manual, error-prone	Automated via 201 semantic relations
Consistency	Varies between conversations	Same structured answer every time
Citability	"I think you should use Extract Class"	"Extract Class (RF-018), priority 0.89"
Offline / Air-gapped	Requires internet for best results	Fully local, single binary

When is this useful?

1. When your AI agent should proactively detect problems, not wait to be asked

The MCP integration auto-triggers on problem descriptions. When a user says "this class does too much", the agent doesn't need to know to ask about God Object — Episteme maps the complaint to SMELL-03, surfaces ranked refactorings, and traces the violation back to first principles. This turns a vague complaint into a structured remediation plan.

2. When you want to reduce token consumption — not burn it on explanations

Without Episteme, an LLM answers "how do I fix a God Object?" by explaining the smell, listing refactorings, describing SOLID principles, and walking through each option — hundreds of tokens per response. With Episteme, one MCP tool call returns SMELL-03 → RF-018 (0.89) → LAW-001. Same expertise at a fraction of the token budget.

3. When you need code analysis connected to remediation — not just detection

Tools like SonarQube detect smells. LLMs can suggest patterns. Episteme does both and connects them: detect Long Method → trace to the laws it violates → rank the refactorings that solve it → show what patterns enforce those refactorings.

4. When isolated pattern knowledge isn't enough — you need the relationships

Knowing what Extract Method does is table stakes. Knowing that it solves Long Method (SMELL-01), which violates Single Responsibility (LAW-001), which is enforced by Facade Pattern (DP-012) — that's a reasoning chain an LLM can't reliably construct on its own. Episteme's 201 semantic relations let AI agents traverse these paths deterministically.

5. When you're making architecture decisions and need evidence, not opinions

"Should I use microservices?" — Episteme connects the question to Conway's Law (LAW-017), SRP (LAW-001), and the Strangler Fig pattern (DP-026), then shows how they relate. Decisions become traceable to engineering laws, not blog posts.

6. When you need consistent, citable engineering advice — not hallucinated recommendations

Every finding references explicit entity IDs (DP-005, RF-001, LAW-021). Recommendations come with priority scores and effort estimates. The same query always returns the same structured answer.

7. When you're working in an air-gapped or restricted network

Episteme runs entirely offline: single binary, local SQLite database, local embeddings via fastembed (ONNX Runtime). No telemetry, no phone-home, no external API calls. Your code and analysis results never leave your machine.

Features

	Feature	Why it matters
🧠	22 GoF Design Patterns	Complete catalog with real-world examples
🔧	66 Refactoring Techniques	Fowler's catalog with code samples
⚖️	56 Software Laws & Principles	SOLID, Conway's Law, CAP Theorem, etc.
👃	17 Code Smell Types	Long Method, God Object, Feature Envy, etc. ¹
🔗	201 Semantic Relations	"solves", "enforces", "violates", "relates_to"
🤖	9 MCP Tools + 4 Agents	High-fidelity AI agent interaction with cross-agent handoffs
🌐	HTTP API Server	REST API on port 58302, auto-started on install
🌍	10 Language Support	Python (AST), Java, TypeScript, Go, Rust, C++, C#, PHP, Ruby, Kotlin
📊	Deterministic Analysis	AST-based Python + regex multi-language, same result every time
🏷️	Citable Knowledge	Every finding links to explicit entity IDs (`RF-001`, `LAW-021`)
🌐	REST API (17 endpoints)	Auth, rate limiting, health probes, Prometheus metrics
📦	Single Binary	No runtime, cross-platform (macOS, Linux, Windows)
🔌	Local Embeddings	fastembed (ONNX Runtime), zero-config semantic search
🐳	Docker Support	Multi-stage build with health checks

¹ Duplicate Code (SMELL-13) and Shotgun Surgery (SMELL-09) require multi-file context and are skipped in single-file mode.

Installation

Option 1: cargo-binstall (Recommended)

cargo binstall episteme    # downloads pre-built binary — no compilation
epis install cursor        # seeds data + starts API server + installs agents

If you don't have cargo-binstall yet: cargo install cargo-binstall

After epis install, the HTTP API server starts automatically on port 58302. MCP is still available -- see registry/mcp.json for manual setup.

Option 2: From Source

git clone https://github.com/epicsagas/Episteme.git
cd Episteme && cargo build --release

Then run the binary for your platform:

Platform	Command
macOS / Linux	`./target/release/epis install --local cursor`
Windows	`.\target\release\episteme.exe install --local cursor`

Option 3: Docker (No Rust Required)

docker-compose up -d

Add to your MCP config file:

Tool	Config file path
Claude Code	`~/.claude.json`
Cursor	`.cursor/mcp.json`
VS Code (Copilot)	`.vscode/mcp.json`

{
  "mcpServers": {
    "episteme": {
      "command": "docker",
      "args": ["exec", "-i", "episteme-api", "episteme", "mcp"]
    }
  }
}

For HTTP transport with bearer token authentication:

{
  "mcpServers": {
    "episteme": {
      "command": "docker",
      "args": ["exec", "-i", "episteme-api", "episteme", "mcp"],
      "headers": {
        "Authorization": "Bearer epis-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
      }
    }
  }
}

Option 4: Pre-built Binaries (No Rust Required)

Download the latest binary for your platform from GitHub Releases:

Platform	File
macOS (Apple Silicon)	`episteme-aarch64-apple-darwin.tar.xz`
Linux (x86_64)	`episteme-x86_64-unknown-linux-gnu.tar.xz`
Linux (ARM64)	`episteme-aarch64-unknown-linux-gnu.tar.xz`
Windows (x86_64)	`episteme-x86_64-pc-windows-msvc.zip`

# macOS / Linux
tar xzf episteme-*.tar.gz
sudo mv episteme /usr/local/bin/

# Windows — extract the zip and add episteme.exe to your PATH

Then install:

epis install cursor

Verify

epis --version
epis stats
epis explore "strategy pattern"    # explore the knowledge graph

Or from inside Claude Code / Codex CLI:

/episteme verify

HTTP API Endpoints

Episteme runs as an always-on HTTP API server on port 58302. Skills and agents call curl http://localhost:58302/... instead of MCP tools. MCP is still available for manual setup -- see registry/mcp.json.

API Endpoints

Knowledge Graph

Method	Endpoint	Purpose
GET	`/health`	Health check
GET	`/search?q=...`	Search knowledge graph
GET	`/graph/{id}`	Get entity by ID
GET	`/graph/{id}/neighbors`	Get related entities
POST	`/graph/path`	Find path between two entities

Code Analysis

Method	Endpoint	Purpose
POST	`/analyze`	Detect code smells
POST	`/refactor`	Suggest refactorings

Tacit Knowledge

Method	Endpoint	Purpose
POST	`/insights`	Add team insight

9 MCP Tools (Legacy)

Canonical Knowledge (6 tools)

Tool	Purpose	Example Use
`search_knowledge`	Semantic search across all entities	"Find patterns for retry logic"
`get_entity`	Get details for specific entity by ID	"Explain Strategy Pattern (DP-023)"
`get_neighbors`	Explore related entities	"What refactorings solve Long Method?"
`find_path`	Find connection between two entities	"How does SRP relate to Extract Class?"
`analyze_code`	Detect code smells via regex/AST analysis	"Review this payment validation code"
`suggest_refactorings`	Ranked refactoring suggestions	"What should I refactor in this class?"

Tacit Knowledge (3 tools)

Tool	Purpose	Example Use
`add_insight`	Record team decisions, lessons learned	"We chose event-driven over polling for X reason"
`search_insights`	Search past team knowledge	"What did we decide about auth middleware?"
`confirm_links`	Validate auto-detected links to canonical entities	Confirm TK-001 relates to SMELL-03

Episteme stores tacit knowledge in a separate database (~/.episteme/user_knowledge.db) and merges it with the canonical graph at runtime via a composite layer. Team insights get auto-linked to patterns, laws, and smells — turning experience into traversable knowledge.

See Tacit Knowledge Architecture for the full design.

4 Specialized Agents (Connected Network)

Agents work together — each analysis ends with Next Steps options that hand off to other agents.

Agent	When to Use	Key Capability	Hands off to
`code-reviewer`	Code smells, SOLID violations	Causation analysis (root cause → downstream symptoms)	advisor, architecture-analyst, refactoring-expert
`episteme-advisor`	Engineering decisions, trade-offs	Multi-entity trade-off chains with action plans	code-reviewer, architecture-analyst, researcher
`episteme-researcher`	Knowledge graph exploration	Connection maps between patterns, laws, smells	advisor, code-reviewer
`architecture-analyst`	Architecture evaluation against laws	Compliance scoring with risk-weighted assessment	advisor, code-reviewer, researcher

Workflow example: code-reviewer detects God Object → traces causation to 3 downstream smells → offers "Apply RF-018" (→ refactoring-expert) or "Deep dive root cause" (→ episteme-advisor) or "Architecture check" (→ architecture-analyst).

Full MCP Integration Guide

CLI Usage

# Analyze code for smells
epis analyze my_code.py --language python --json
episteme infer my_code.py

# Explore the knowledge graph
epis explore "strategy pattern"
epis graph path DP-005 RF-001   # e.g. Factory Method → Extract Method

# Build the RAG index
epis build

# Start servers
epis api              # REST API on :58302
episteme mcp --http       # MCP server on :43175 (legacy)
episteme web --port 8080  # Web UI (interactive graph explorer)

# Distribution packaging
episteme dist --out-dir release/

Documentation

Document	Description
Quick Start	Step-by-step setup, first run, troubleshooting
MCP Integration Guide	Tool reference, agent examples, conversation flows
Tacit Knowledge Architecture	Two-database design, insight lifecycle, schema
Alcove Ecosystem Comparison	Storage models, search capabilities, use-case matrix
Alcove Integration Guide	Dual-context workflows, setup, best practices
API Reference	REST endpoints, authentication, examples
Evaluation System	Search quality benchmarks, FP reduction, composite scoring
Distribution	Release packaging and deployment
Development & Contributing	Architecture, how to contribute
Changelog	Release history and version notes

Embedding Models

Episteme uses local embeddings for semantic search — no external API required.

Default: MultilingualE5Small (included)

epis install ships a pre-built database with 913 chunks already embedded using MultilingualE5Small (384 dimensions, ONNX Runtime). This means:

No indexing needed after install — search works immediately
Fully offline — model runs locally via fastembed (ONNX Runtime)
Multilingual — supports English, Korean, Japanese, Chinese, and 90+ languages

Using a custom model

To switch to a different local model, set the environment variable and rebuild:

# Set your preferred model
export EPISTEME_EMBEDDING_MODEL=AllMiniLML6V2

# Rebuild the index with the new model
epis build --rebuild

Available local models (ONNX, no API key needed):

Model	Dimensions	Best for
`MultilingualE5Small` (default)	384	Multilingual, balanced speed/quality
`AllMiniLML6V2`	384	English-focused, fast
`BGEBaseEN`	768	English, higher quality

See Supported Embedding Models for the full catalog.

Using OpenAI embeddings

# Enable OpenAI provider
export EPISTEME_OPENAI_API_KEY=sk-...
export EPISTEME_EMBEDDING_MODEL_PROVIDER=openai
export EPISTEME_OPENAI_EMBED_MODEL=text-embedding-3-small

# Rebuild with OpenAI
epis build --rebuild

Requires the openai-embeddings feature flag at compile time.

Note: After switching models, you must run epis build --rebuild to regenerate embeddings. The database stores which model was used and will warn if there is a mismatch.

Configuration

Environment Variables

# Data locations
EPISTEME_DATA_DIR=~/.episteme/data
EPISTEME_DB_PATH=~/.episteme/db/episteme.db

# API server
EPISTEME_API_HOST=0.0.0.0
EPISTEME_API_PORT=58302
EPISTEME_API_KEY=your-secret-key

# MCP server
EPISTEME_MCP_HOST=127.0.0.1
EPISTEME_MCP_PORT=43175
EPISTEME_MCP_TOKEN=epis-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

# Embedding models
EPISTEME_EMBEDDING_MODEL=MultilingualE5Small   # local (fastembed), default: MultilingualE5Small
EPISTEME_OPENAI_EMBED_MODEL=text-embedding-3-small  # OpenAI, requires OPENAI_API_KEY

Troubleshooting

episteme command not found after install

Platform	Fix
macOS / Linux	`export PATH="$HOME/.cargo/bin:$PATH"` — add to `~/.bashrc` or `~/.zshrc` to persist
Windows	Add `%USERPROFILE%\.cargo\bin` to your system PATH, or open a new terminal

MCP tools not appearing in Claude Code / Cursor

The HTTP API server starts automatically on port 58302 after epis install. Skills use curl http://localhost:58302/... to interact with Episteme. MCP is still available for manual setup -- see registry/mcp.json.

Port already in use

epis api --port 58303   # use a different port

Slow first startup

Episteme builds a local embedding index on first run. This takes 30–60 seconds and is a one-time cost. Subsequent starts are instant.

Compilation errors during cargo install

Ensure Rust 1.95+ is installed:

rustup update stable
rustup show   # confirm active toolchain

More help: QUICKSTART.md troubleshooting section · Open an issue

Ecosystem: Alcove Integration

Episteme has two layers for capturing knowledge: the canonical graph (universal patterns, laws, smells) and the tacit knowledge layer (TK-* — team insights auto-linked to canonical entities). For richer project documentation — architecture decisions, coding conventions, onboarding guides, technical debt registers — Alcove is the recommended companion.

flowchart LR
    U["Developer"] --> A["AI Agent"]
    A -->|"What pattern applies?"| E["Episteme<br/>Canonical Graph"]
    A -->|"Quick insight?"| T["Episteme<br/>Tacit Knowledge (TK-*)"]
    A -->|"Team decisions?"| L["Alcove<br/>Project Docs"]
    E --> R["Grounded Recommendation"]
    T --> R
    L --> R

Episteme vs Alcove — when to use which

Scenario	Use	Why
Detect code smells in a module	Episteme `analyze_code`	Regex/AST detection + ranked refactoring suggestions
Record a momentary insight ("we always hit N+1 here")	Episteme `add_insight`	Auto-links to relevant canonical entities (SMELL-, LAW-)
Find relationship between SRP and Extract Class	Episteme `find_path`	Multi-hop graph traversal across entity types
Start documentation for a new project	Alcove `init_project`	7 core templates (PRD, ARCHITECTURE, DECISIONS, ...) auto-generated
Record a formal architecture decision (ADR)	Alcove DECISIONS.md	Structured ADR format with context, options, consequences
Check if docs are outdated or have broken links	Alcove `lint_project`	Detects WIP/TODO/DEPRECATED markers, orphan files, stale dates
Enforce naming conventions or required sections	Alcove `validate_docs`	Policy-based validation with pass/warn/fail
Import Obsidian notes for agent access	Alcove `promote_document`	Symlink vaults + BM25/vector indexing
Ground a recommendation in both principles and team rules	Both	Universal knowledge + team-specific constraints

Tacit Knowledge (TK-*) vs Alcove Docs

Episteme's tacit knowledge layer is designed for short, momentary insights that auto-connect to the knowledge graph — "we chose event-driven over polling because X", auto-linked to DP-018 (Observer) and LAW-012 (Fail Fast). Alcove handles structured, long-lived documentation — full ADRs with sections, architecture diagrams, coding standards, onboarding checklists.

	Episteme TK-*	Alcove
Granularity	Atomic free-text insight	Structured multi-section document
Auto-linking	Keyword detection → canonical entities	wikilinks between docs
Lifecycle	Create + search	Full CRUD + validate + lint + audit + backup
Search	FTS5 keyword	BM25 + vector hybrid (CJK support)
Best for	Quick observations, lessons learned	Formal decisions, project scaffolding, doc governance

Alcove manages 3 tiers of documentation (7 core + 19 supplementary + 15 public files), provides BM25 + vector hybrid search with CJK support, and integrates with Obsidian vaults. It includes policy validation, semantic linting (broken links, stale markers, orphans), and git-based backups.

Full analysis: Alcove Ecosystem Comparison — storage models, search capabilities, feature completeness, and use-case decision matrix.

Usage patterns: Alcove Integration Guide — agent workflows, code review with dual context, and setup instructions.

Roadmap

Released

epis install — one-command data setup from GitHub Releases
Homebrew tap (epicsagas/tap/episteme) — macOS Apple Silicon + Linux (x86_64 + ARM64)
Claude Code & Codex CLI plugin marketplace support
README translations — 9 languages (ko, ja, zh-CN, zh-TW, de, fr, es, pt, hi)
Cross-platform builds — macOS, Linux, Windows with DirectML GPU acceleration

Planned

Custom Entities — Add team-specific patterns and code smells
Multilingual Metadata — Entity titles and summaries in CJK languages
Interactive Tutorials — In-app guided tours for MCP tools
Team Metrics — Aggregate pattern usage across organization

Contributing

Contributions welcome! See DEVELOPMENT.md for the architecture overview and contribution guide.

# Run tests
cargo test

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt

# Run evaluation suite (measures search quality, smell detection accuracy, graph traversal)
python3 benchmarks/eval_runner.py full

See Evaluation System for details on the 6 eval suites, composite scoring, and regression detection.

Questions? Open a discussion or file an issue.

License

Apache 2.0 — see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 320 Commits
.aider		.aider
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github		.github
benchmarks		benchmarks
db		db
dist		dist
docs		docs
meta		meta
monitoring		monitoring
raw		raw
registry		registry
src		src
tests		tests
web		web
.aider.conf.yml		.aider.conf.yml
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
DEVELOPMENT.md		DEVELOPMENT.md
Dockerfile		Dockerfile
GEMINI.md		GEMINI.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
dist-workspace.toml		dist-workspace.toml
docker-compose.yml		docker-compose.yml
install.ps1		install.ps1
install.sh		install.sh
rust-toolchain.toml		rust-toolchain.toml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Quick Start

Claude Code

Codex CLI

Other tools

Manual install

Verify

Try it in 30 seconds

Why Episteme?

How is this different from just prompting an LLM well?

When is this useful?

Features

Installation

Option 1: cargo-binstall (Recommended)

Option 2: From Source

Option 3: Docker (No Rust Required)

Option 4: Pre-built Binaries (No Rust Required)

Verify

HTTP API Endpoints

API Endpoints

Knowledge Graph

Code Analysis

Tacit Knowledge

9 MCP Tools (Legacy)

Canonical Knowledge (6 tools)

Tacit Knowledge (3 tools)

4 Specialized Agents (Connected Network)

CLI Usage

Documentation

Embedding Models

Default: MultilingualE5Small (included)

Using a custom model

Using OpenAI embeddings

Configuration

Environment Variables

Troubleshooting

Ecosystem: Alcove Integration

Episteme vs Alcove — when to use which

Tacit Knowledge (TK-*) vs Alcove Docs

Roadmap

Contributing

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages