episteme 0.3.4

Knowledge graph for software engineering — design patterns, refactorings, and laws for AI agents
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
<p align="center">
<img src="docs/assets/icon.png" alt="Episteme" width="60%" />
</p>

<p align="center"><sub>Episteme (ἐπιστήμη) — Greek for "systematic knowledge, scientific understanding"</sub></p>

<p align="center">An offline-first, single-binary knowledge graph that connects design patterns, refactoring techniques, and software laws through semantic relationships.<br><b>Built for AI agents first</b> — integrate software engineering expertise directly into Claude Code, Cursor, and other MCP-compatible tools.</p>

<p align="center">Written in Rust · Single binary · Fully offline</p>

---

<p align="center">
  <a href="https://github.com/epicsagas/Episteme/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/epicsagas/Episteme?style=for-the-badge&labelColor=0d1117&color=ffd700&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/Episteme/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/epicsagas/Episteme?style=for-the-badge&labelColor=0d1117&color=2ecc71&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/Episteme/issues"><img alt="Issues" src="https://img.shields.io/github/issues/epicsagas/Episteme?style=for-the-badge&labelColor=0d1117&color=ff6b6b&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/Episteme/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/epicsagas/Episteme?style=for-the-badge&labelColor=0d1117&color=58a6ff&logo=git&logoColor=white" /></a>
</p>
<p align="center">
  <a href="https://crates.io/crates/episteme"><img alt="Crates.io" src="https://img.shields.io/crates/v/episteme?style=for-the-badge&labelColor=0d1117&color=fc8d62&logo=rust&logoColor=white" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-3fb950?style=for-the-badge&labelColor=0d1117" /></a>
  <a href="https://blog.rust-lang.org/"><img alt="Rust" src="https://img.shields.io/badge/rust-1.95+-d73a49?style=for-the-badge&labelColor=0d1117&logo=rust&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/Episteme/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/epicsagas/Episteme/ci.yml?style=for-the-badge&labelColor=0d1117&color=e67e22&logo=githubactions&logoColor=white" /></a>
  <a href="https://buymeacoffee.com/epicsaga"><img alt="Buy Me a Coffee" src="https://img.shields.io/badge/buy_me_a_coffee-FFDD00?style=for-the-badge&labelColor=0d1117&logo=buymeacoffee&logoColor=black" /></a>
</p>

<p align="center">
  English |
  <a href="docs/i18n/ja/">日本語</a> |
  <a href="docs/i18n/ko/">한국어</a> |
  <a href="docs/i18n/de/">Deutsch</a> |
  <a href="docs/i18n/fr/">Français</a> |
  <a href="docs/i18n/zh-CN/">简体中文</a> |
  <a href="docs/i18n/zh-TW/">繁體中文</a> |
  <a href="docs/i18n/pt/">Português</a> |
  <a href="docs/i18n/es/">Español</a> |
  <a href="docs/i18n/hi/">हिन्दी</a>
</p>

---

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/features.png">
  <img src="docs/assets/features.png" align="center" width="100%" alt="Episteme Features Overview" />
</picture>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/demo.gif">
  <img src="docs/assets/demo.gif" align="center" width="100%" alt="Episteme Demo" />
</picture>

---

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

```bash
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

```bash
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:

```bash
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

```bash
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]#option-3-docker-no-rust-required |

### Verify

```bash
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.

```bash
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?

<details>
<summary><b>1. When your AI agent should proactively detect problems, not wait to be asked</b></summary>

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.
</details>

<details>
<summary><b>2. When you want to reduce token consumption — not burn it on explanations</b></summary>

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.
</details>

<details>
<summary><b>3. When you need code analysis connected to remediation — not just detection</b></summary>

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.
</details>

<details>
<summary><b>4. When isolated pattern knowledge isn't enough — you need the relationships</b></summary>

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.
</details>

<details>
<summary><b>5. When you're making architecture decisions and need evidence, not opinions</b></summary>

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

<details>
<summary><b>6. When you need consistent, citable engineering advice — not hallucinated recommendations</b></summary>

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.
</details>

<details>
<summary><b>7. When you're working in an air-gapped or restricted network</b></summary>

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.
</details>

---

## 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)

```bash
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

```bash
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)

```bash
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` |

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

For HTTP transport with bearer token authentication:
```json
{
  "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](https://github.com/epicsagas/Episteme/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` |

```bash
# 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:
```bash
epis install cursor
```

### Verify

```bash
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](docs/tacit-knowledge.md) 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](docs/mcp-integration-guide.md)

---

## CLI Usage

```bash
# 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]QUICKSTART.md | Step-by-step setup, first run, troubleshooting |
| [MCP Integration Guide]docs/mcp-integration-guide.md | Tool reference, agent examples, conversation flows |
| [Tacit Knowledge Architecture]docs/tacit-knowledge.md | Two-database design, insight lifecycle, schema |
| [Alcove Ecosystem Comparison]docs/alcove-ecosystem.md | Storage models, search capabilities, use-case matrix |
| [Alcove Integration Guide]docs/alcove-integration.md | Dual-context workflows, setup, best practices |
| [API Reference]docs/api.md | REST endpoints, authentication, examples |
| [Distribution]docs/distribution.md | Release packaging and deployment |
| [Development & Contributing]DEVELOPMENT.md | Architecture, how to contribute |
| [Changelog]CHANGELOG.md | Release history and version notes |

---

## Configuration

### Environment Variables

```bash
# 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
```

See [Supported Embedding Models](https://github.com/epicsagas/llm-kernel/blob/main/EMBEDDING_MODELS.md) for the full catalog of local (ONNX) and OpenAI models with dimensions and descriptions.

---

## 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**
```bash
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:
```bash
rustup update stable
rustup show   # confirm active toolchain
```

> More help: [QUICKSTART.md troubleshooting section]QUICKSTART.md#troubleshooting · [Open an issue]https://github.com/epicsagas/Episteme/issues

---

## 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](https://github.com/epicsagas/alcove)** is the recommended companion.

```mermaid
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](docs/alcove-ecosystem.md) — storage models, search capabilities, feature completeness, and use-case decision matrix.

**Usage patterns**: [Alcove Integration Guide](docs/alcove-integration.md) — agent workflows, code review with dual context, and setup instructions.

---

## Roadmap

**Released**
- [x] `epis install` — one-command data setup from GitHub Releases
- [x] Homebrew tap (`epicsagas/tap/episteme`) — macOS Apple Silicon + Linux (x86_64 + ARM64)
- [x] Claude Code & Codex CLI plugin marketplace support
- [x] README translations — 9 languages (ko, ja, zh-CN, zh-TW, de, fr, es, pt, hi)
- [x] **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](DEVELOPMENT.md) for the architecture overview and contribution guide.

```bash
# Run tests
cargo test

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt
```

Questions? [Open a discussion](https://github.com/epicsagas/Episteme/discussions) or [file an issue](https://github.com/epicsagas/Episteme/issues).

---

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.