A system that delivers only verified knowledge to AI coding agents.
When AI coding agents receive too much unfiltered context, they don't get smarter — they get noisier. Unverified hypotheses are treated as facts, revoked decisions persist as instructions, and irrelevant information buries the critical rules. The result: hallucinations, silent mistakes, and costly rework.
Knowledge Distillery takes a different path: collect broadly, distill rigorously, deliver minimally.
A 3-layer architecture with a convention-based air gap separates raw information from verified knowledge:
- History Archive — Raw data preserved without loss (Slack, Linear, PR reviews, AI session transcripts)
- Distillation Pipeline — AI-driven refinement with automated quality gates, extracting only confirmed decisions and validated anti-patterns
- Knowledge Vault — A curated SQLite store of distilled insights, accessible only through the
knowledge-gateCLI
The agent never touches raw data. It only sees what has survived distillation.
- Convention-based air gap: Operational isolation between raw data and the agent's workflow — not perfect enforcement, but sufficient and pragmatic
- AI-autonomous distillation: LLMs extract and compress; humans provide strategic oversight, not item-by-item approval
- Context Gate: Domain-based selective filtering ensures agents receive only task-relevant knowledge, not the entire vault
- Append-only, two types only: The vault contains only Facts and Anti-Patterns — no confidence scores, no hedging
Executable skills in plugins/knowledge-distillery/skills/ are the source of truth for pipeline behavior.
| Document | Description |
|---|---|
| Design Philosophy | Why this architecture exists — the rationale behind information control for AI agents |
| Implementation Design | How it works — pipeline design, vault schema, runtime policies, deployment as a Claude Code Plugin |
| Adoption Guide | How to install the plugin, initialize a repository, and start using the vault |
| Tool Evaluation | Adopted and rejected tools with rationale |
The knowledge-gate CLI is the sole access path to the knowledge vault (.knowledge/vault.db). Set KNOWLEDGE_VAULT_PATH to override the default vault location.
Agent Runtime — query rules before modifying code:
| Command | Purpose |
|---|---|
query-paths [--ids-only] <filepath> |
Resolve file path to domains → return a lightweight summary index, or IDs only |
query-domain [--ids-only] <domain> |
Query rules by domain name → return a lightweight summary index, or IDs only |
search [--ids-only] <keyword> |
FTS5 full-text keyword search → return a lightweight summary index, or IDs only |
get <id> |
Retrieve full entry details (including body) |
get-many <id>... |
Retrieve full details for multiple entries in one call |
list [--ids-only] |
Summary list of all active entries, or IDs only |
Domain — explore and manage the domain registry:
| Command | Purpose |
|---|---|
domain-info <domain> |
Domain details (description, patterns, entry count) |
domain-list [--status X] [--ids-only] |
List domains or emit a lightweight domain ID index |
domain-resolve-path <filepath> |
Reverse-lookup file path to domains |
domain-add, domain-merge, domain-split, domain-deprecate |
Registry lifecycle |
domain-paths-set, domain-paths-add, domain-paths-remove |
Path pattern management |
domain-report |
Domain health diagnosis |
Loading — add entries to the vault:
| Command | Purpose |
|---|---|
add --type <type> --title ... --claim ... --body ... --domain ... [flags] |
Add entry with validation |
_pipeline-insert |
Pipeline-only bulk INSERT (JSON stdin) |
Utility — setup and maintenance:
| Command | Purpose |
|---|---|
init-db [path] |
Create a new vault from bundled schema |
migrate |
Apply schema migrations |
curate |
Interactive curation queue resolution |
Examples:
# Query rules before editing a file
knowledge-gate query-paths src/api/auth/login.ts
# Query a domain with an ultra-light ID-only index
knowledge-gate query-domain --ids-only payment
# Fetch multiple full entries after a lightweight discovery step
knowledge-gate get-many global-convention service-rule
# Check which domains a file belongs to
knowledge-gate domain-resolve-path src/services/payment.rb
# Preload a lightweight domain ID index for navigation
knowledge-gate domain-list --ids-only
# Search for rules by keyword
knowledge-gate search "callback"Run knowledge-gate help for full usage details.
Knowledge Distillery supports two delivery paths:
- Portable agent skills:
npx skills add https://github.com/ether-moon/knowledge-distillery/tree/main/plugins/knowledge-distillery --skill '*' -a codex - Claude Code Plugin: install with
claude plugin installto use the/knowledge-distillery:*namespace
Each skill owns the scripts and assets it needs. The knowledge-gate CLI and schema live inside the knowledge-gate skill; hook templates and workflow assets live inside the setup skill. Running setup installs lifecycle hooks into the active host's repo-local configuration. The runtime remains vendor-neutral and uses sqlite3; pipeline and setup operations also use jq.
The repository doubles as a Claude plugin marketplace. .claude-plugin/marketplace.json points to plugins/knowledge-distillery/, whose skills/ directory is also discoverable by portable skill installers.
Proof of concept. The design is intentionally kept open to change — tight constraints and exhaustive safeguards make future iteration harder. Focus is on real-world usability first.
TBD