Skip to content

README.md

Latest commit

 

History

History
149 lines (113 loc) · 6.07 KB

README.md

File metadata and controls

149 lines (113 loc) · 6.07 KB

"The only true wisdom is in knowing you know nothing." — Socrates

📚 wiki-vault

Lightweight knowledge vault MCP server for structured wiki compilation.

wiki-vault is not a note-taking app. It is a structured knowledge substrate — a typed graph of interconnected research artifacts that grows autonomously as AI agents compile findings. BM25 search, typed edges, batch validation, zero LLM dependencies. The vault is the persistent memory layer where research knowledge crystallizes into reusable structure.

⚡ What It Does

  • 🔍 BM25 full-text search — ranked retrieval across all vault pages with type/tag filters and contextual snippets
  • 🕸️ Typed knowledge graph — 10 edge types connecting 9 entity types, with BFS traversal and orphan detection
  • 🩺 Batch validation — 5 check types (broken links, orphans, missing frontmatter, duplicate edges, stale index) with auto-fix
  • 📊 Graph statistics — global metrics (density, orphans, type distribution) and per-node connectivity analysis
  • 🔄 Incremental indexing — only re-indexes changed files, full rebuild available on demand
  • 📖 Obsidian-compatible — standard markdown + YAML frontmatter + [[wikilinks]], browsable without modification

🎯 Design Philosophy

  • Single unified vault. All knowledge in one place regardless of research domain. Cross-domain connections emerge naturally from the graph.
  • CC handles CRUD directly. File creation, editing, deletion are CC's native operations. The MCP server provides only what CC cannot do efficiently: ranked search, graph traversal, batch validation.
  • Sources are immutable. Raw material is preserved verbatim. Synthesis and evolution happen in wiki pages.
  • Graph is first-class. Every page connects via typed edges. Orphans are failures, not features.
  • 兵法书, not pipeline. Skills teach principles and provide SOPs — CC decides strategy and execution autonomously.

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│  MCP Server (8 tools)                                   │
│  vault_search · vault_add_edge · vault_query_graph      │
│  vault_graph_stats · vault_lint · vault_index           │
│  vault_info · vault_edge_audit                          │
├─────────────────────────────────────────────────────────┤
│  Core Modules                                           │
│  index.ts (BM25) · graph.ts (edges+traversal) · lint.ts│
├─────────────────────────────────────────────────────────┤
│  Vault (filesystem)                                     │
│  9 entity dirs · _edges.jsonl · _index.json · _schema.md│
└─────────────────────────────────────────────────────────┘

Tools

Tool Description
vault_search BM25 full-text search with type/tag filters and snippets
vault_add_edge Create typed edge between pages (validates, deduplicates)
vault_query_graph BFS traversal from node with direction/depth/type filters
vault_graph_stats Global or per-node graph statistics and orphan detection
vault_lint Batch validation (5 check types) with optional auto-fix
vault_index Rebuild search index (incremental or full)
vault_info Returns vault metadata (root, directories, types, stats) for session init
vault_edge_audit Scan edges and report missing [[wikilinks]] in source page bodies

Skills (9)

Level Skill Purpose
Tactic knowledge-compilation Compile research findings into vault pages
Tactic vault-maintenance Vault health upkeep and cleanup
SOP wiki-search Search before creating (deduplication)
SOP wiki-graph-query Explore node neighborhood
SOP wiki-add-edge Create typed relationships
SOP wiki-ingest-source Write immutable source pages
SOP wiki-compile-page Create/update synthesized pages
SOP wiki-lint-fix Run lint and optionally fix
SOP wiki-edge-audit Audit and fix missing wikilinks for edges

Entity Types

Type Directory Purpose
source sources/ Immutable raw material
concept concepts/ Synthesized understanding
entity entities/ Named entities (people, orgs, tools)
claim claims/ Testable assertions with confidence
relation relations/ Named relationships
question questions/ Open research questions
evidence evidence/ Supporting/refuting evidence
failure failures/ Documented failed approaches
topic topics/ High-level topic containers

Edge Types

Edge Type Semantics
component_of A is part of B
instance_of A is an example of B
supported_by A has evidence from B
contradicts A conflicts with B
supersedes A replaces B
derived_from A was built from B
addresses A answers/solves B
raises A creates/implies B
failed_for A didn't work for B
related_to Weak association

🚀 Quick Start

# Install
npm install

# Run tests (83 tests)
npm test

# Start MCP server
VAULT_ROOT=/path/to/vault npx @yogsoth-ai/wiki-vault

MCP Configuration

Add to your .mcp.json:

{
  "wiki-vault": {
    "type": "stdio",
    "command": "npx",
    "args": ["@yogsoth-ai/wiki-vault"],
    "env": { "VAULT_ROOT": "/path/to/your/vault" }
  }
}

📄 License

Apache-2.0

Part of the Yogsoth AI ecosystem. Built by Pthahnix.