Echo Wiki

A generic, LLM-maintained knowledge base system. Ingest sources, compile a structured wiki, browse in Obsidian. Works with any domain — AI research, finance, healthcare, marketing, or anything else.

Read the docs for full setup guide, configuration reference, and usage examples.

How It Works

The full pipeline: sources → /ingest → raw/ receipts → /compile → wiki/ knowledge → used via Obsidian, /query (with workspace write-back), and agents — with the deterministic script rails underneath. Editable source: echo-wiki-flow.excalidraw.

  URLs / Files / PDFs
         |
         v
  +--------------+
  |   /ingest    |  Fetch + clean source -> raw/
  +--------------+
         |
         v
  +--------------+
  |   /compile   |  Extract entities, build articles -> wiki/
  +--------------+
         |
         v
  +--------------+
  |  /rebuild    |  Stage + validate a replacement (after deletion)
  +--------------+
         |
         v
  +--------------+
  |   Obsidian   |  Browse, graph view, backlinks
  +--------------+

/rebuild is only needed after manually deleting raw source files. Normal workflow is /ingest → /compile.

Newly ingested sources always include a visible Markdown heading so compiled claims can cite a stable evidence location. See the validation guide for the one-time migration required by legacy headingless raw sources.

The LLM writes all wiki content. You provide sources, the LLM maintains wiki/. You never edit KB articles directly — just read them in Obsidian. You can create your own notes and drafts in wiki/workspaces/.

raw/                          wiki/ (Obsidian vault)
├── blogs/                    ├── _index.md        <- Master index
│   └── source-article.md    ├── _backlinks.md    <- Cross-reference map
├── papers/                   ├── _log.md          <- Activity log (auto-created)
├── people/                   ├── concepts/        <- Default entity types
├── substacks/                │   └── topic.md
├── github/                   ├── people/          <- (configurable via
├── internal/                 │   └── person.md
└── media/                    ├── tools/           <-  entity_types in config)
                              │   └── tool.md
                              ├── sources/         <- Source summaries
                              │   └── summary.md
                              └── workspaces/      <- Actor workspaces
                                  └── my-notes/    <- Your notes

Onboard Your Repository

Give your coding agent a complete Echo Wiki checkout and the absolute path to your destination Git repository. The /onboard skill has separate paths for fresh repositories and repositories with existing artifacts. It previews setup, preserves existing files, and reports conflicts with concrete next steps.

# Fresh repository
Read /path/to/echo-wiki/.claude/skills/onboard/SKILL.md and follow it.
Set up /path/to/company-kb as "Company Knowledge" with company,
product, engineering, marketing, and research domains.

# Repository with existing documents
Read /path/to/echo-wiki/.claude/skills/onboard/SKILL.md and follow it.
Onboard /path/to/existing-repo. Keep its artifacts in place,
preserve its instructions and hooks, and propose one initial import.

If the skill is already discoverable, use /onboard <destination> in Claude Code, or select onboard in Codex’s skill picker ($onboard where supported). Otherwise, explicitly reading its file works without assuming a particular agent's slash-command support. The agent needs Git, Bash and Ruby; local Markdown ingestion does not require API keys.

Onboarding automatically adds relative .agents/skills/ links for Codex, sharing the canonical .claude/skills/ definitions. Existing instances can add missing links with the link repair command. Conflicting skill names are preserved and reported before any installation writes.

Existing wiki/, raw/, or _meta/ collisions require a decision before installation. Onboarding does not automatically relocate documents, synchronize cloud sources, or upgrade existing instances.

See Getting Started for bootstrap commands, examples, and verification.

Configuration

All customization lives in one file: _meta/wiki.config.yaml

wiki:
  name: "My Wiki"
  description: "What this wiki is about"

domains:
  - name: "topic"
    label: "Topic Label"

entity_types:                  # What kinds of articles to create
  - name: concept              # (defaults shown — customize for your domain)
    dir: concepts
    label: Concepts
    description: "Ideas, theories, patterns"
  - name: person
    dir: people
    label: People
    description: "Researchers, authors, key figures"
  - name: tool
    dir: tools
    label: Tools
    description: "Software, platforms, frameworks"
  - name: source-summary
    dir: sources
    label: Sources
    description: "Summaries of ingested raw sources"

vault:
  dir: wiki
  default_workspace: my-notes

defaults:
  decay_rate: medium    # fast | medium | slow
  confidence: medium    # high | medium | speculative

See .env.example for required API keys.

Core Operations

Command	What it does
/onboard <destination>	Set up a fresh or existing repository with preview and verification
/ingest <url>	Fetch URL, save clean markdown to raw/
/ingest <path>	Import local file (md, pdf) to raw/
/compile <path>	Compile raw source into wiki articles
/compile all	Recompile entire wiki
/rebuild	Stage, validate, and commit a KB replacement from remaining raw sources
/index	Rescan wiki/ and update _index.md and _backlinks.md
/lint	Run semantic checks, produce report
/lint all	Lint entire wiki
/query <question>	Answer from the wiki with citations; file durable answers and capture unsupported questions as knowledge gaps
/context <product-area>	Create or refresh a concise, evidence-backed context pack for a component or product area
/maintain	Refresh indexes, write diagnostics and a prioritized queue, and append the activity log without changing factual knowledge

Keeping Content Fresh

Echo Wiki is command-driven, not a background synchronizer. New sources flow through /ingest → /compile, while context packs, durable answers, knowledge gaps, and the maintenance queue refresh only when you run /context, /query, or /maintain again. For the complete change-to-next-step guide—including manual raw imports, source deletion, and the current same-URL replacement limitation—see Keeping Content Fresh.

Workspaces

Users and agents can create content alongside KB articles in wiki/workspaces/:

wiki/workspaces/
├── my-notes/              <- Default human workspace (ships with template)
│   ├── research-log.md
│   └── todo.md
├── content-creator/       <- Agent workspace (created on demand)
│   └── drafts/
├── knowledge-maintenance/ <- System-managed context packs and knowledge gaps
│   ├── context/
│   └── gaps/
└── social-media/          <- Agent workspace
    └── drafts/

• Zero registration — just create a directory under workspaces/
• Agents and humans are peers — same structure, same rules
• Cross-zone wikilinks — workspace notes can link to KB articles and vice versa
• Rebuild-safe — /rebuild never touches workspaces/
• Run /index after creating workspace content to update the master index

Engineering Context Packs

/context <product-area> creates a compact starting page for developers and coding agents. It summarizes the current architecture, constraints, decisions, open questions, and the articles to read next. Context packs are rebuild-safe derived content in workspaces/knowledge-maintenance/context/; factual paragraphs link to exact supporting locations in raw/ rather than creating a second knowledge store.

When /query cannot provide a fully evidence-backed answer, it records the question, search scope, missing evidence, and a suggested next source in workspaces/knowledge-maintenance/gaps/. Repeated unanswered questions update the same note, so the wiki's next improvements are driven by real developer and agent usage.

/maintain is safe, manual maintenance: it refreshes the generated index/backlinks files, writes the lint report and prioritized maintenance queue, and appends the activity log when you run it. It surfaces broken evidence, stale or contradictory articles, recurring knowledge gaps, and orphan/duplicate candidates, but never changes factual content by itself.

Data Flow

                    /ingest
                       |
    URL -----> [Tavily/Firecrawl] -----> raw/<category>/<source>.md
    File ----> [copy + frontmatter] --/        |
                                               |
                    /compile                   |
                       |                       |
    raw source --------+                       |
         |                                     |
         v                                     |
    Extract entities (per config entity_types)  |
         |                                     |
         v                                     |
    For each entity:                           |
      exists? --> MERGE (add info, keep old)   |
      new?    --> CREATE (full frontmatter)     |
         |                                     |
         v                                     |
    Run reindex.sh (_index + _backlinks)       |
    Run validate.sh (schema gate)              |
    Append to _log.md                          |
         |                                     |
         v                                     |
    wiki/ <-- ready for Obsidian               |
                                               |
                    /rebuild                    |
                       |                       |
    [delete raw] --> stage KB --> replay sources --> validate --> replace live KB
                     (workspaces preserved; failure leaves live KB unchanged)

Validation

Deterministic scripts (no LLM):

• ./hooks/validate.sh [--json] [--all|--staged|<paths>] — full frontmatter schema (required fields, enums, dates, tags vs domains), source-path existence, filename rules, wikilink resolution, structure integrity; --json prints one JSON object instead of text
• ./hooks/reindex.sh — regenerates _index.md and _backlinks.md deterministically; skills never hand-write them
• Pre-commit hook, when installed, validates the complete staged snapshot before each commit

Semantic lint (/lint, on-demand, LLM):

• Contradictory claims across articles
• Stale content past decay thresholds
• Orphaned articles (from explicit _No inbound links._ markers)
• Missing concepts (referenced but no article)
• Duplicate concepts under different names
• Source fidelity (sampled) — claims must trace to cited raw sources

Token count (post-commit, informational):

./hooks/token-count.sh    # Run manually anytime
# Also runs after each commit (never blocks)

Directory Structure

echo-wiki/
├── _meta/
│   ├── wiki.config.yaml      # Your wiki configuration
│   ├── prompts/               # Shared step references (structure-check)
│   └── schemas/               # Frontmatter validation schema
├── raw/                       # Source documents (append-only, backend)
├── wiki/                      # Obsidian vault (user-facing)
│   ├── concepts/              # KB: default entity type directories
│   ├── people/                #     (configurable via entity_types in config)
│   ├── tools/
│   ├── sources/
│   ├── workspaces/            # Actor workspaces (human + agent)
│   │   └── my-notes/          # Default human workspace
│   ├── _index.md              # Master index
│   ├── _backlinks.md          # Cross-reference map
│   └── _log.md                # Activity log (auto-created by skills)
├── output/reports/            # Lint reports, query results, token counts
├── hooks/                     # validation, indexing, pre-commit, and rebuild transaction scripts
├── tests/                     # Fixture-based tests for the hooks (run-tests.sh)
├── .agents/skills/            # Codex links to the canonical skills below
├── .claude/skills/            # Agent Skills (onboard, ingest, compile, rebuild, lint, index, query, context, maintain)
├── docs/                      # VitePress documentation site
├── .env.example               # API key template
├── CLAUDE.md                  # Claude Code instructions
└── README.md

Provider Support

Echo Wiki uses the Agent Skills open standard. Works with:

• Claude Code — via CLAUDE.md + .claude/skills/
• Codex — via AGENTS.md + .agents/skills/ links to .claude/skills/
• Gemini CLI — via GEMINI.md + .claude/skills/
• Any Agent Skills-compatible agent

License

MIT