Cadabby

Epistemically Auditable LLM Wiki Engine for Humans & AI Agents

Cadabby is a zero-dependency, local-first engine and Model Context Protocol (MCP) server for maintaining living, high-density knowledge vaults. It enables AI agents (Claude Code, Google Antigravity, OpenHands, etc.) and humans (via Obsidian or CLI) to collaboratively build, cross-reference, and audit knowledge graphs anchored by Open Knowledge Foundation (OKF) epistemic trust tiers.

Key Highlights

• Zero Runtime Dependencies: Built with 100% pure Python standard library (CPython >= 3.11). No pip dependencies.
• Flat Canonical Synthesis: wiki/ is strictly flat (wiki/*.md); physical subdirectories in wiki/ are forbidden. Navigation topology is editorial via Maps of Content (type: moc).
• Autonomous Cognitive Domains: Partition knowledge into independent cognitive domains (e.g., customers/, projects/) governed by localized {domain}/AGENTS.md manifests and arbitrary nested folder structures.
• Disposable SQLite FTS5 Cache: Ephemeral, high-performance full-text search and 1-hop graph traversals. Delete .cadabby/cache.db at any time with zero data loss.
• Epistemic Trust Tiers: Every note carries cryptographically bound attestation (human-reviewed, machine-confirmed, stale-verified, or unverified).
• Drift-Induced Downgrade: If an agent or user alters note prose without re-verification, its trust tier automatically downgrades to stale-verified (verification debt).
• Deterministic Gap Report: index.md is a focused worklist of entry points, unfiled notes, raw queue, and verification debt—never a bloated catalog.
• Normative Six-Gate Linting: Automated validation for schema, layout, link consistency, provenance, graph connectivity, and verification integrity.
• Universal Harness Portability: Works out-of-the-box with Claude Code (.mcp.json), Antigravity (native plugin & subagents), Gemini CLI, and Obsidian.

1. Installation

Cadabby is a command-line application, so install it as a tool rather than as a library. Either of these puts cadabby on your PATH in its own isolated environment, leaving your system Python untouched:

uv tool install cadabby    # recommended
pipx install cadabby       # equivalent

Verify:

cadabby --help

Why not pip install? It works, but it drops Cadabby into whichever environment happens to be active, which makes the install easy to lose track of and easy to break with an unrelated upgrade. Nothing imports cadabby as a library, so there is no reason to put it on an interpreter's import path.

Cadabby has zero runtime dependencies (pure CPython >= 3.11 standard library), so installation never pulls in a transitive dependency tree.

Contributing

Working on Cadabby itself:

git clone https://github.com/naikoob/cadabby.git
cd cadabby
uv sync                    # or: pip install -e .

# Fast parallel test execution across all CPU cores (~5.5s, 353 tests):
python3 tests/run_parallel.py

# Canonical sequential test suite:
PYTHONPATH=src python3 -m unittest discover tests

2. Initializing a Vault

To scaffold a complete, production-ready knowledge vault:

# Initialize a new vault with Obsidian integration:
cadabby init --vault my-vault --name my-vault --obsidian
cd my-vault

This creates a standardized 3-layer vault layout:

my-vault/
├── .cadabby.json         # Vault configuration, trust multipliers & identities
├── .mcp.json             # Universal MCP server config (for Claude Code, Cursor, etc.)
├── AGENTS.md             # Canonical constitution / operational rules for all AI agents
├── CLAUDE.md             # Thin pointer delegating to AGENTS.md
├── GEMINI.md             # Thin pointer delegating to AGENTS.md
├── STYLE.md              # Vault-specific prose and citation guidelines
├── index.md              # Deterministic gap report (entry points, unfiled notes, raw queue, verification debt)
├── log.md                # Append-only activity ledger
│
├── raw/                  # Ground truth sources (PDFs, raw text, research papers)
│
├── wiki/                 # Flat canonical knowledge domain (strictly wiki/*.md)
│   ├── Architecture.md   # Concepts, entities, syntheses (typed via frontmatter)
│   └── Systems-MOC.md    # Maps of Content (type: moc) governing vault topology
│
├── customers/            # (Optional) Cognitive domain with autonomous AGENTS.md
│   ├── AGENTS.md         # Domain constitution & schema rules
│   └── acme-corp/        # Flexible, arbitrary nested subdirectory layout
│
├── templates/            # (Optional) Starter note templates, excluded from discovery
│
├── .agents/skills/       # Reusable skills: librarian and technician
├── .claude/commands/     # Claude Code slash commands (/ingest, /vault-status, /vault-lint)
└── .obsidian/            # (Optional) Pre-tuned Obsidian desktop settings

3. How to Use Cadabby

Workflow A: Using AI Agents (Claude Code, Cursor, Windsurf)

1. Drop a ground truth document into raw/:

   cp ~/Downloads/attention-paper.pdf raw/attention-paper.pdf
   

2. Start your agent inside the vault directory:

   claude
   

   Claude Code automatically reads .mcp.json, launches cadabby mcp, and reads CLAUDE.md $\rightarrow$ AGENTS.md.

3. Interact naturally using slash commands or chat:

   > /ingest raw/attention-paper.pdf
   

   The agent will:

   • Call vault_search to check if related concepts already exist.
   • Call vault_ground to inspect existing notes and their 1-hop links.
   • Call vault_scaffold_note to draft wiki/Flash-Attention.md citing raw/attention-paper.pdf.
   • Add [[wikilinks]] to existing notes and suitable Maps of Content ([[AI-Systems-MOC]]).
   • Call vault_verify_note stamping the note with agent:claude-code. (The index.md gap report and the log.md ledger are kept up to date implicitly; no manual sync needed).

Workflow B: Using Google Antigravity

1. Install the Antigravity plugin:

   cadabby install --antigravity
   

2. Open the vault in Antigravity. The plugin provides:
   • An MCP sidecar running cadabby mcp.
   • Two specialized personas:
     • @librarian: Researches raw sources, checks prior knowledge, scaffolds notes, and resolves links.
     • @technician: Runs vault_lint, verifies cache health, and tracks verification debt.

Workflow C: Human Reading & Editing (Obsidian & CLI)

1. Open my-vault/ in Obsidian:
   • Wikilinks [[Note-Stem]] resolve automatically across the flat wiki and nested cognitive domains.
   • index.md acts as your gap report, while Maps of Content (type: moc) curate navigation topology.
   • The core Templates plugin works as-is. Cadabby reads .obsidian/templates.json, skips the folder it names so your templates are never mistaken for notes, and can scaffold from them:

     cadabby scaffold "Flash-Attention" --type concept --desc "IO-aware attention" --template concept
     

     The template's body is used with {{title}} substituted; its frontmatter is discarded, because OKF frontmatter is engine-owned. Foam's .foam/templates/ needs no configuration.
   • To start from Cadabby's own note shape, scaffold the starters once:

     cadabby init --vault my-vault --obsidian-templates
     

     This writes templates/Concept.md and templates/MOC.md and points Obsidian at them, so Insert template produces correct OKF frontmatter. It is opt-in because it reserves templates/, which would otherwise be a normal cognitive domain; an existing template folder is honored instead, and a templates/ that already holds notes is refused rather than swallowed. Starters fill title but leave description empty — the plugin cannot prompt for it — so a fresh note fails cadabby lint with FIELD_MISSING until you write one. That is deliberate: a TODO placeholder would pass lint and quietly seed a field that feeds search ranking.
2. Review and certify notes: When a human inspects a note and certifies its accuracy:

   cadabby verify wiki/Flash-Attention --human
   

   This binds the attestation to the exact sha256 of the note body and upgrades its trust tier to human-reviewed ($2.0\times$ search boost).
3. If anyone edits the note body: Cadabby automatically detects the SHA-256 mismatch and demotes the note to stale-verified (verification debt), prompting re-review.

4. Cognitive Domains & Domain Manifests

Cadabby supports modular, multi-domain knowledge architectures. While wiki/ serves as the canonical knowledge base with a strictly flat layout governed by Maps of Content (MOCs), you can partition knowledge into independent Cognitive Domains simply by creating top-level directories (e.g. customers/, projects/, research/, team/). Custom domains fully support arbitrary nested directory structures.

Creating a Cognitive Domain with AGENTS.md

Drop an AGENTS.md file into the root of any top-level domain folder to configure validation schemas and define agent directives:

---
description: Customer accounts, CRM dossiers, and stakeholders
allowed_types:
  - account
  - stakeholder
  - interaction
require_sources: false
---

# Customers Domain Directives

1. Every customer note must include account tier and primary contact.
2. Link stakeholder profiles using `[[Stakeholder-Name]]`.
3. Do not store sensitive secrets or credentials in dossiers.

Manifest Configuration Options

Permissive vs. Strict Domains

• Canonical wiki/ Domain: Strictly flat (wiki/*.md). Dynamic open typing by default (unless restricted by wiki/AGENTS.md). Governed by Maps of Content (type: moc).
• Permissive Domains (no AGENTS.md or allowed_types: null): Any non-empty note type and any folder hierarchy are allowed without triggering lint errors.
• Strict Domains (allowed_types specified): Linter enforces valid types, while allowing cross-domain wikilinks ([[Note-Stem]]) to resolve smoothly across all domains. Custom domains support nested folders.

Every discovered domain is searchable. There is no per-domain opt-out: exclusion happens before discovery (reserved names, dot-prefixed directories, build folders), so anything that became a domain is knowledge you put in the vault deliberately. To narrow a query, pass --domain / domain at the call site rather than hiding content from every future search. See SPECIFICATION.md §2.2.

Step-by-Step: Creating a New Cognitive Domain

1. Choose a Top-Level Directory Name: Pick a domain name at the vault root (e.g. customers/, projects/, research/). Ensure the name does not conflict with reserved engine directories (raw/, log/, .cadabby/, .obsidian/, .git/, .agents/, .claude/, or environment folders like .venv/).
2. Create the Domain Manifest (Optional but Recommended): Create {domain}/AGENTS.md to define schema validation and operational directives:

   mkdir -p customers
   cat << 'EOF' > customers/AGENTS.md
   ---
   description: "Customer accounts and dossiers"
   allowed_types:
     - account
     - contact
   require_sources: false
   ---
   # Customer Directives
   Cross-link all accounts to primary contact notes.
   EOF
   

3. Scaffold Notes in the Domain:
   • Via CLI:

     cadabby scaffold "Acme-Corp" --domain customers --type account --description "Enterprise account dossier"
     

   • Via MCP: Call vault_scaffold_note(title="Acme-Corp", domain="customers", type="account", description="Enterprise account dossier").
4. Verify Domain Discovery & Epistemic Health:

   cadabby status
   

   The status report displays registered domains, their note counts, and schema status.
5. Validate Schemas & Integrity:

   cadabby lint
   

   The linter validates note frontmatter against the domain's allowed_types and layout rules.

How AI Agents Consume Domain Directives

• MCP Resources: Cadabby exposes vault://domains (inventory of all discovered domains) and domain://{name}/directives (the markdown body of {domain}/AGENTS.md).
• Grounding Enrichment: When an agent calls vault_ground on a note, Cadabby automatically embeds the note's domain definition and localized directives into the response payload.

5. MCP Architecture (7 Tools & 2 Resources)

Conforming to §5.1-§5.2 of the Technical Specification, Cadabby exposes exactly 7 atomic tools and 2 dynamic resources to AI agents:

Atomic Tools

Dynamic Resources

6. CLI Command Reference

7. Epistemic Trust Tiers

Status multipliers apply on top of trust tiers:

• evergreen: $1.1\times$
• active: $1.0\times$
• draft: $0.7\times$
• deprecated: $0.3\times$
• stub: $0.2\times$

8. Development & Testing

Cadabby uses standard-library unittest with zero test dependencies:

# Fast parallel test execution across all CPU cores (~5.5s, 353 tests):
python3 tests/run_parallel.py

# Parallel execution with verbose output or target filtering:
python3 tests/run_parallel.py -v
python3 tests/run_parallel.py test_cache

# Canonical sequential test suite:
PYTHONPATH=src python3 -m unittest discover tests