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.
• Multi-Domain Cognitive Architecture: Partition knowledge into independent cognitive domains (e.g., customers/, projects/, wiki/) governed by localized AGENTS.md manifests and schemas.
• 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).
• 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), 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/your-org/cadabby.git
cd cadabby
uv sync                    # or: pip install -e .
uv run python -m unittest discover -s 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 catalog auto-generated by cadabby
├── log.md                # Append-only activity ledger
│
├── raw/                  # Ground truth sources (PDFs, raw text, research papers)
│
├── wiki/                 # Canonical knowledge domain (5 typed subdirectories)
│   ├── entities/         # Concrete objects, tools, datasets, libraries
│   ├── concepts/         # Abstract ideas, algorithms, techniques
│   ├── syntheses/        # Cross-domain integrations and summaries
│   ├── comparisons/      # Trade-off evaluations (e.g. SQLite-vs-DuckDB)
│   └── guides/           # Actionable procedures and runbooks
│
├── customers/            # (Optional) Custom cognitive domain
│   ├── AGENTS.md         # Domain constitution & schema rules
│   └── acme-corp/        # Flexible, unconstrained subdirectory layout
│
├── .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/concepts/Flash-Attention.md citing raw/attention-paper.pdf.
   • Add [[wikilinks]] to existing notes.
   • Call vault_verify_note stamping the note with agent:claude-code. (Catalog index.md and activity log.md 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 subdirectories.
   • index.md acts as your curated table of contents.
2. Review and certify notes: When a human inspects a note and certifies its accuracy:

   cadabby verify wiki/concepts/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 strictly enforced 5-type directory structures, you can partition knowledge into independent Cognitive Domains simply by creating top-level directories (e.g. customers/, projects/, research/, team/).

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
searchable: true
schema:
  allowed_types:
    - account
    - stakeholder
    - interaction
  require_sources: false
  enforce_layout: 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

Field	Type	Default	Purpose
description	string	"<Domain> domain"	Human-readable domain description.
searchable	bool	true	Whether notes in this domain are indexed and returned in vault_search.
schema.allowed_types	list[str]	null (unrestricted)	Allowed type: values in frontmatter. Violations trigger ENUM_INVALID in cadabby lint.
schema.require_sources	bool	false	When true, notes in this domain must specify non-empty sources: [...].
schema.enforce_layout	bool	false	When true, notes must live in a subfolder matching their type (like in wiki/). When false, arbitrary directory nesting is permitted.

Permissive vs. Strict Domains

• 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.

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

Tool	Purpose
vault_search	Epistemic BM25 full-text search with trust tier boosts, domain filters, and status multipliers.
vault_ground	Retrieves full content, localized domain directives, and 1-hop graph neighborhood (links, backlinks, sources).
vault_status	Epistemic health snapshot: tier counts, domain breakdown, verification debt, and unprocessed raw/ files.
vault_scaffold_note	Scaffolds a new typed note in any domain with valid OKF frontmatter and generated attribution.
vault_update_note	Non-destructive frontmatter patch, section append, or section replace with optimistic lock.
vault_verify_note	Cryptographically binds an agent:<client_id> attestation to the body SHA-256 (refuses human:*).
vault_lint	Runs the six normative epistemic lint gates and returns typed diagnostics for self-healing.

Dynamic Resources

Resource URI	MIME Type	Description
vault://domains	application/json	Real-time inventory of all discovered cognitive domains, descriptions, and schema flags.
domain://{domain}/directives	text/markdown	Localized operational instructions and guidelines from {domain}/AGENTS.md.

---

6. CLI Command Reference

Command	Description	Example
cadabby init	Scaffold a new vault with all config & skills	cadabby init --vault my-vault --obsidian
cadabby sync	Scan files, update SQLite cache & rebuild index.md	cadabby sync
cadabby status	Report note counts, trust tiers, and verification debt	cadabby status
cadabby search	Epistemic BM25 search with trust boosts & domain filters	cadabby search "attention mechanism" --domain wiki
cadabby ground	Retrieve note content and 1-hop neighborhood	cadabby ground wiki/concepts/Attention
cadabby scaffold	Scaffold a new typed note in any domain	cadabby scaffold "Transformer" --type concept --domain wiki --desc "Attention model"
cadabby update	Patch frontmatter or append/replace sections	cadabby update wiki/concepts/Transformer --replace-section "Overview:New text"
cadabby verify	Stamp cryptographic attestation on note	cadabby verify wiki/concepts/Transformer --human
cadabby lint	Run the six normative epistemic linting gates across all domains	cadabby lint
cadabby audit	Check Git blame provenance of human attestations	cadabby audit --require-signed
cadabby mcp	Launch the JSON-RPC 2.0 stdio MCP server	cadabby mcp
cadabby install	Register MCP configs in Antigravity or Claude Code	cadabby install --antigravity

---

7. Epistemic Trust Tiers

Tier	Multiplier	Description
human-reviewed	$2.0\times$	Certified by a validated human reviewer. Body matches sha256.
machine-confirmed	$1.0\times$	Synthesized and verified by an automated AI agent.
stale-verified	$0.8\times$	Previously verified, but note prose drifted without re-review (verification debt).
unverified	$0.5\times$	Newly drafted or imported without verification.

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

# Run all unit and integration tests (105 tests):
PYTHONPATH=src python3 -m unittest discover -s tests -v

All 12 falsifiable acceptance criteria from §10 are validated in tests/test_acceptance.py.