agent-wiki

The knowledge base that makes AI agents smarter over time.

Instead of retrieving raw fragments every query (RAG), your agent compiles, refines, and interlinks knowledge — like a team wiki that writes itself.

Works with Claude Code, Cursor, Windsurf, and any MCP client. Also installable as a native skill for Claude Code. No LLM built in — your agent IS the intelligence.

agent-wiki's built-in 3D graph view

Pages as nodes, [[wikilinks]] as edges, edits push live — included in the main package.

Quick Start

Option A: MCP Server (Cursor, Windsurf, Claude Desktop, any MCP client)

Add to your MCP client config:

{
  "mcpServers": {
    "agent-wiki": {
      "command": "npx",
      "args": ["-y", "@agent-wiki/mcp", "serve", "--wiki-path", "/path/to/knowledge"]
    }
  }
}

Option B: Native Skill (Claude Code)

npm install -g @agent-wiki/mcp

# Install as Claude Code plugin
agent-wiki install claude-code

Option C: CLI only

npx @agent-wiki/mcp call wiki_search '{"query": "deployment"}'

Option D: 3D Graph Viewer

See your wiki as a realtime 3D knowledge graph — edits push live via SSE. Included in the main package, no separate install needed.

npm install -g @agent-wiki/mcp
agent-wiki web --wiki-path ./wiki --open

Heavy browser libs (3d-force-graph, three.js) load from a CDN at runtime. See graph-viewer/README.md for the full feature list and interaction guide.

That's it. Your agent now has a persistent, structured knowledge base.

Why Not RAG?

| | RAG | agent-wiki | |---|---|---| | Approach | Retrieve fragments at query time | Build and maintain compiled knowledge | | Memory | Stateless — forgets after each query | Persistent — knowledge accumulates | | Quality | Raw chunks, often noisy | Curated, structured, interlinked | | Cost | Embedding + retrieval every query | One-time compilation, free reads | | Contradictions | Invisible — buried in source docs | Flagged automatically by lint | | Source tracking | Lost after retrieval | Full provenance chain (raw -> wiki) |

Features

| Feature | Description | |---------|-------------| | Batch Mode | Generic batch tool + semantic pipelines — collapse multi-step workflows into single requests | | Knowledge Pipelines | Unified knowledge_ingest modes — end-to-end ingest/digest/write-back loop without expanding the public tool surface | | Structured Extraction | PDF (per-page), DOCX, XLSX (per-sheet), PPTX (per-slide) — segments with source provenance | | Immutable Sources | SHA-256 verified raw/ layer — write-once, tamper-proof, full provenance | | Knowledge Compilation | Agent builds structured wiki pages from raw sources — not retrieve-and-forget | | BM25 Search | Field-weighted scoring, synonym expansion, fuzzy matching, CJK tokenization — zero LLM | | Hybrid Search | Optional BM25+vector re-ranking via @xenova/transformers — enable with one config line, no external API | | Auto-Classification | Zero-LLM heuristic assigns entity types and tags across 10 categories | | Multi-Level Indexes | Auto-generated index.md at every directory level — nested topic hierarchies with sub-topic navigation | | Self-Checking Lint | Catches contradictions, broken links, orphan pages, stale content | | Coverage Report | raw_coverage tells the agent which raw sources have not yet been compiled into any wiki page — drives active knowledge completion | | Atlassian Import | One-command Confluence pages and Jira issues with full hierarchy. Supports both Atlassian Cloud (*.atlassian.net) and self-hosted Server / Data Center, with auto-routed API endpoints and Bearer / Basic auth handling. | | File Versioning | Auto-version same-name files, query latest, list all versions | | Language Plugins | Deterministic parsers + cross-file knowledge graphs for legacy code. COBOL shipped with field lineage in three families (shared-copybook reuse, CALL ... USING boundary, cross-program DB2 flow), DB2 column-level pairing, dynamic CALL resolution, and a precision / recall eval harness. JCL planned. See Language Plugins below. | | Skill Install | One-command install as native skill for Claude Code and compatible clients | | Git-Native | Plain Markdown — diffable, blameable, revertable | | 3D Graph Viewer | Built-in — realtime 3D graph of pages and [[wikilinks]], edits push live over SSE. Run agent-wiki web. |

Architecture

Three immutability layers, inspired by how compilers work:

| Layer | Mutability | Role | |-------|-----------|------| | raw/ | Immutable | Source documents — write-once, SHA-256 verified | | wiki/ | Mutable | Compiled knowledge — structured pages that improve over time | | schemas/ | Reference | Entity templates — consistent structure across knowledge types |

Design Principles

1. Raw is immutable — Source documents are write-once, SHA-256 verified. Ground truth never changes.
2. Wiki is mutable — Compiled knowledge improves with every interaction.
3. No LLM dependency — Zero API keys, zero cost per operation. Your agent IS the intelligence.
4. Self-checking — Lint catches structural issues and flags potential contradictions.
5. Knowledge compounds — Every write enriches the whole wiki. Synthesis creates higher-order understanding.
6. Provenance matters — Every wiki claim traces back to raw sources.
7. Git-native — Plain Markdown. Every change is diffable, blameable, and revertable.

Integration

| Method | Best For | Setup | |--------|----------|-------| | MCP Server | Cursor, Windsurf, Claude Desktop, any MCP client | Add to .mcp.json | | Native Skill | Claude Code (native plugin) | agent-wiki install claude-code | | CLI | Any agent with shell access | agent-wiki call <tool> '{json}' | | 3D Graph Viewer | Visual exploration of the whole wiki | agent-wiki web -w ./wiki |

Language Plugins

agent-wiki extends to source-code analysis via language plugins — deterministic parsers + cross-file knowledge graphs, no LLM. Each plugin emits structured artifacts (raw/parsed/<lang>/) and writes wiki pages with full provenance back to the source files.

| Language | Status | Capabilities | |----------|--------|--------------| | COBOL | Shipped | AST parser (fixed-format with mainframe alphanumeric sequence areas + free-format). Programs, copybooks, sections, CALL (incl. dynamic-call constant propagation), COPY / REPLACING (incl. via-replacing cohorts and REPLACING-aware inferred matching), EXEC SQL (DB2 column-level host-var pairing), EXEC CICS, file access modes. Field lineage in three families: shared-copybook reuse (deterministic + inferred), CALL ... USING boundary, cross-program DB2 flow. Depth-bounded impact queries via code_query. | | JCL | Planned | Job / step / dataset / proc extraction, batch-flow wiki pages, dataset-mediated cross-program lineage. See PRD Phase 2. |

Tier-gate decisions (Phase C precision gates, dynamic-call resolver, DB2 column pairing) are evaluated against ground-truth fixtures via a built-in precision / recall eval harness — each PR runs against a committed NIST CCVS slice as a corpus-level regression anchor.

Hybrid Search Setup

Upgrade from keyword-only to semantic search with two steps:

1. Add to .agent-wiki.yaml:

search:
  hybrid: true

2. Run wiki_admin once to rebuild and embed all pages:

agent-wiki call wiki_admin '{"action":"rebuild"}'

The first run downloads the Xenova/all-MiniLM-L6-v2 model (~90 MB) from HuggingFace Hub and caches it locally. After that, every wiki_write automatically keeps the vector index up to date.

Hybrid mode blends BM25 + cosine similarity scores. If embedding fails for any reason, search falls back to pure BM25 — queries never fail.

See Search configuration for weight tuning.

Documentation

• MCP Tools (15 public tools) & Entity Types
• Configuration, CLI & Security
• Request Optimization — Batch Digest, Pagination, Context Limits

Acknowledgment

Inspired by Andrej Karpathy's LLM Wiki concept — the idea that AI agents should compile and maintain knowledge, not just retrieve raw fragments. This project is an independent, full implementation of that vision.

License

MIT