convez.ai
MCP ServerProdutividadeIntermediário
epicsagas

Episteme: Grafo de Conhecimento para Engenharia de Software

epicsagas/Episteme

Grafo de conhecimento offline para expertise em engenharia de software em agentes IA

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema de grafo de conhecimento offline-first construído em Rust que conecta padrões de design, técnicas de refatoração e leis de software através de relações semânticas. Otimizado para agentes IA — integra expertise de engenharia de software diretamente em Claude Code, Cursor e ferramentas MCP compatíveis.

Instalação

$npx convez-ai epicsagas/Episteme

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
3
Acompanhando
0
Saúde
100%
Último commit
há 3 dias
Versão
v0.3.16
Issues abertas
1
Contribuidores
2

Casos de uso

  • Enriquecer contexto técnico de agentes IA durante desenvolvimento
  • Sugerir padrões de design e técnicas de refatoração baseadas em relacionamentos semânticos
  • Manter base de conhecimento centralizada e offline sobre software laws e best practices

Veredito

Ferramenta sólida e bem construída em Rust para elevar o nível de assistência técnica em agentes IA. Abordagem offline-first é prática, mas o valor real depende da qualidade e amplitude do grafo de conhecimento mantido.

README

A tradução para o português deste README ainda está na fila.




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

MethodCommand
Homebrewbrew install epicsagas/tap/episteme
Shell scriptcurl --proto '=https' --tlsv1.2 -LsSf https://github.com/epicsagas/Episteme/releases/latest/download/episteme-installer.sh | sh
PowerShellirm https://github.com/epicsagas/Episteme/releases/latest/download/episteme-installer.ps1 | iex
cargocargo binstall episteme ⚡ or cargo install episteme
DockerSee 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 promptEpisteme + LLM
Proactive detectionOnly if the user asks the right questionAuto-triggers on problem descriptions
Token efficiencyLong explanations + multiple follow-up turnsOne tool call returns structured result
Relationship traversalOne-hop at best, often hallucinatedMulti-hop graph traversal, verified
Cross-referencingManual, error-proneAutomated via 201 semantic relations
ConsistencyVaries between conversationsSame structured answer every time
Citability"I think you should use Extract Class""Extract Class (RF-018), priority 0.89"
Offline / Air-gappedRequires internet for best resultsFully local, single binary

When is this useful?

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.

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.

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.

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.

"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.

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.

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

FeatureWhy it matters
🧠22 GoF Design PatternsComplete catalog with real-world examples
🔧66 Refactoring TechniquesFowler's catalog with code samples
⚖️56 Software Laws & PrinciplesSOLID, Conway's Law, CAP Theorem, etc.
👃17 Code Smell TypesLong Method, God Object, Feature Envy, etc. ¹
🔗201 Semantic Relations"solves", "enforces", "violates", "relates_to"
🤖9 MCP Tools + 4 AgentsHigh-fidelity AI agent interaction with cross-agent handoffs
🌐HTTP API ServerREST API on port 58302, auto-started on install
🌍10 Language SupportPython (AST), Java, TypeScript, Go, Rust, C++, C#, PHP, Ruby, Kotlin
📊Deterministic AnalysisAST-based Python + regex multi-language, same result every time
🏷️Citable KnowledgeEvery finding links to explicit entity IDs (RF-001, LAW-021)
🌐REST API (17 endpoints)Auth, rate limiting, health probes, Prometheus metrics
📦Single BinaryNo runtime, cross-platform (macOS, Linux, Windows)
🔌Local Embeddingsfastembed (ONNX Runtime), zero-config semantic search
🐳Docker SupportMulti-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:

PlatformCommand
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:

ToolConfig 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:

PlatformFile
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

MethodEndpointPurpose
GET/healthHealth check
GET/search?q=...Search knowledge graph
GET/graph/{id}Get entity by ID
GET/graph/{id}/neighborsGet related entities
POST/graph/pathFind path between two entities

Code Analysis

MethodEndpointPurpose
POST/analyzeDetect code smells
POST/refactorSuggest refactorings

Tacit Knowledge

MethodEndpointPurpose
POST/insightsAdd team insight

9 MCP Tools (Legacy)

Canonical Knowledge (6 tools)

ToolPurposeExample Use
search_knowledgeSemantic search across all entities"Find patterns for retry logic"
get_entityGet details for specific entity by ID"Explain Strategy Pattern (DP-023)"
get_neighborsExplore related entities"What refactorings solve Long Method?"
find_pathFind connection between two entities"How does SRP relate to Extract Class?"
analyze_codeDetect code smells via regex/AST analysis"Review this payment validation code"
suggest_refactoringsRanked refactoring suggestions"What should I refactor in this class?"

Tacit Knowledge (3 tools)

ToolPurposeExample Use
add_insightRecord team decisions, lessons learned"We chose event-driven over polling for X reason"
search_insightsSearch past team knowledge"What did we decide about auth middleware?"
confirm_linksValidate auto-detected links to canonical entitiesConfirm 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.

AgentWhen to UseKey CapabilityHands off to
code-reviewerCode smells, SOLID violationsCausation analysis (root cause → downstream symptoms)advisor, architecture-analyst, refactoring-expert
episteme-advisorEngineering decisions, trade-offsMulti-entity trade-off chains with action planscode-reviewer, architecture-analyst, researcher
episteme-researcherKnowledge graph explorationConnection maps between patterns, laws, smellsadvisor, code-reviewer
architecture-analystArchitecture evaluation against lawsCompliance scoring with risk-weighted assessmentadvisor, 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

DocumentDescription
Quick StartStep-by-step setup, first run, troubleshooting
MCP Integration GuideTool reference, agent examples, conversation flows
Tacit Knowledge ArchitectureTwo-database design, insight lifecycle, schema
Alcove Ecosystem ComparisonStorage models, search capabilities, use-case matrix
Alcove Integration GuideDual-context workflows, setup, best practices
API ReferenceREST endpoints, authentication, examples
Evaluation SystemSearch quality benchmarks, FP reduction, composite scoring
DistributionRelease packaging and deployment
Development & ContributingArchitecture, how to contribute
ChangelogRelease 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):

ModelDimensionsBest for
MultilingualE5Small (default)384Multilingual, balanced speed/quality
AllMiniLML6V2384English-focused, fast
BGEBaseEN768English, 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

PlatformFix
macOS / Linuxexport PATH="$HOME/.cargo/bin:$PATH" — add to ~/.bashrc or ~/.zshrc to persist
WindowsAdd %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

ScenarioUseWhy
Detect code smells in a moduleEpisteme analyze_codeRegex/AST detection + ranked refactoring suggestions
Record a momentary insight ("we always hit N+1 here")Episteme add_insightAuto-links to relevant canonical entities (SMELL-, LAW-)
Find relationship between SRP and Extract ClassEpisteme find_pathMulti-hop graph traversal across entity types
Start documentation for a new projectAlcove init_project7 core templates (PRD, ARCHITECTURE, DECISIONS, ...) auto-generated
Record a formal architecture decision (ADR)Alcove DECISIONS.mdStructured ADR format with context, options, consequences
Check if docs are outdated or have broken linksAlcove lint_projectDetects WIP/TODO/DEPRECATED markers, orphan files, stale dates
Enforce naming conventions or required sectionsAlcove validate_docsPolicy-based validation with pass/warn/fail
Import Obsidian notes for agent accessAlcove promote_documentSymlink vaults + BM25/vector indexing
Ground a recommendation in both principles and team rulesBothUniversal 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
GranularityAtomic free-text insightStructured multi-section document
Auto-linkingKeyword detection → canonical entitieswikilinks between docs
LifecycleCreate + searchFull CRUD + validate + lint + audit + backup
SearchFTS5 keywordBM25 + vector hybrid (CJK support)
Best forQuick observations, lessons learnedFormal 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.

Ver o original no GitHub

Bom para

Relacionados