Ariadne

In Greek myth, Ariadne gives Theseus the thread that lets him navigate the labyrinth. Ariadne gives AI agents a thread through a complex knowledge labyrinth.

An agent skill package for building Markdown knowledge vaults that AI agents can navigate, maintain, and operate reliably. Designed for ChatGPT/Codex, Claude Code, and other runtimes that support the skills protocol; accepted cross-runtime behavioral evidence is still being expanded.

The core pattern: humans choose what enters, agents compile raw material into a linked wiki, and plain Markdown remains the source of truth. Document renderers are replaceable; Obsidian is an optional, recommended frontend, and its Bases and other view features remain derived layers.

flowchart LR
  Human(["Human\nSources · notes · requests"])
  Agent(["AI agent"])

  subgraph Vault["Markdown knowledge vault"]
    Operating["Operating graph\nAGENTS · navigation · routing"]
    Checkpoints["Canonical scope checkpoints\nstable ID · path · lifecycle"]
    Topology["Topology synchronizer\npreview · authorize · recover"]
    Knowledge["Knowledge graph\nresearch · concepts · decisions"]
    Views["Derived optional views\nregistry · Markdown map · Canvas"]
    Validator["Deterministic validator\nwhole vault · scoped profiles"]
  end

  Human --> Agent
  Agent -->|"enters through"| Operating
  Operating -->|"selects the smallest context"| Checkpoints
  Checkpoints --> Knowledge
  Topology -->|"maintains generated cores"| Checkpoints
  Checkpoints -.->|"generates"| Views
  Validator -.->|"checks"| Operating
  Validator -.->|"checks"| Checkpoints
  Validator -.->|"checks"| Knowledge
  Validator -.->|"checks"| Views
  Views -.->|"surfaces state and gaps"| Human

Requirements

• A filesystem-accessible folder for the Markdown knowledge vault.
• Node.js with npm/npx available for installing skills and running the bundled validator and vault-registration scripts.
• A skills-capable agent runtime, such as ChatGPT/Codex, Claude Code, or another runtime that supports the skills protocol.

Optional Document Renderers

No particular renderer is required for agent workflows. Obsidian is not required; use any Markdown-compatible editor or viewer that preserves the underlying files. Obsidian is the recommended and most-tested frontend when you want native backlinks, graph, Canvas, Bases, Kanban, or Dataview. Obsidian users may optionally install kepano/obsidian-skills for companion Markdown, Bases, Canvas, extraction, and CLI mechanics.

Ariadne has no project dependency installation or build step. Its scripts use only built-in Node.js modules; npx skills copies the skill package into supported agent runtimes.

Install

Install into all supported skill targets (ChatGPT/Codex, Claude Code, and others):

npx skills add https://github.com/pariyar07/ariadne \
  --global \
  --agent '*' \
  --copy \
  --yes

Install for a specific agent:

# Claude Code
npx skills add https://github.com/pariyar07/ariadne \
  --global \
  --agent claude-code \
  --copy \
  --yes

# ChatGPT/Codex
npx skills add https://github.com/pariyar07/ariadne \
  --global \
  --agent openai \
  --copy \
  --yes

List available skills:

npx skills add https://github.com/pariyar07/ariadne --list

Update

Update globally installed skills:

npx skills update -g -y

Reinstall Ariadne from GitHub when you want to force a fresh copy:

npx skills add https://github.com/pariyar07/ariadne \
  --global \
  --agent '*' \
  --copy \
  --yes

During local Ariadne development, reinstall from your checkout:

npx skills add /path/to/ariadne \
  --global \
  --agent '*' \
  --copy \
  --yes

List installed global skills:

npx skills list -g

Updating skills does not migrate existing vault content. After updating, run the validator against important vaults, and run global discovery doctor if you use machine-level vault discovery:

node skills/validator/scripts/validate_vault.js "/path/to/vault"
node skills/vault/scripts/register_vault.js --agents codex,claude,gemini --doctor

The research lifecycle skill names changed atomically. Existing copied skills, generated vault instructions, saved prompts, and external schedulers need an explicit migration pass; see Research Lifecycle Migration.

Latest release: Ariadne v0.3.4 — Obsidian Canvas Metadata Compatibility.

Skills

Start with ariadne:vault to bootstrap a new vault. Most other skills operate on an existing vault; ariadne:workspace-instructions operates on a workspace that may link back to registered Ariadne context.

Weekly Maintenance Automation

Recurring maintenance is best handled as an automation prompt that invokes the existing skills, not as a separate skill. Start with ariadne:validator, follow with ariadne:maintenance, route research-semantic drift to ariadne:research-stewardship, and call ariadne:research-synthesis only when an authorized synthesis pass needs a disposition.

See docs/guides/weekly-maintenance-automation.md for a Codex-ready prompt, Claude Code adaptation notes, subagent boundaries, and the optional durable report variant.

Current Direction

Ariadne's implemented foundation now covers discovery, scoped navigation, knowledge capture, research governance, closeout, deterministic validation, and recoverable scope topology.

The current product question is whether that structure measurably improves outcomes over a plain Markdown folder, whether non-Codex runtimes follow the same contracts in practice, and whether external users sustain it. Validation and real-user evidence should precede more architecture.

Conditional value directions after that evidence include:

• cross-domain synthesis across scope-level research hubs
• explicit relationship notes for connections between domains
• recurring daily or weekly vault briefs
• stale question resurfacing
• contradiction review across old decisions, beliefs, and newer synthesis

The design constraint stays the same: agents should not need to read the whole vault to be useful. They should follow ordered explicit routes, preserve bounded write authority, return to canonical evidence, and keep Markdown as the source of truth.

How It Works

Three Layers

Every vault created with Ariadne has three layers:

• Knowledge Graph — research, concepts, entities, relationships, decisions, and domain workstreams
• Operating Graph — agent instructions (AGENTS.md), routing matrices, workflows, intake queues, and templates
• View Layer — Bases (.base files), canvases, and dashboards as live queries over the Markdown source of truth

Recursive Scope Model

The vault is a tree of scopes, not a flat folder. Each adopted scope has an immutable scope_id, a canonical path and lifecycle in its exact 00 Index.md, plus four marker-managed checkpoint surfaces. The root owns global policy; each child inherits parent rules and adds only local deltas. Markdown descriptors and checkpoints are canonical, while registry, map, and Canvas views are derived.

Vault root (global policy)
├── Agent/            ← global routing and workflows
├── Bases/            ← global view layer
├── Domains/
│   ├── Alpha/        ← child scope (inherits root)
│   │   ├── AGENTS.md ← local deltas only
│   │   ├── Agent/    ← local routing
│   │   └── Bases/    ← scoped views
│   └── Beta/         ← another child scope

Navigation Layers

Agents navigate through a layered structure — no cold reading of raw notes:

00 Index.md               → strategic map
Agent/00 Agent Navigation → routing map
Agent/Task Routing Matrix → task entry selector
Folder hubs               → detailed local maps
Thread hubs               → deep synthesis notes
Bases                     → dynamic inspection layer

Wikilink Resolution

Navigation files (AGENTS.md, 00 Index.md, Agent/) always use path-qualified wikilinks so agents arriving cold have zero ambiguity. Content notes may use bare links because agents always arrive via a qualified navigation file, never cold.

The validator resolves wikilinks to real vault files, including Markdown notes, Base files, Canvas files, and attachments. Orphan checks remain Markdown-only.

Validation

Run the validator from a vault root:

node /path/to/skills/validator/scripts/validate_vault.js "/path/to/vault"

Use --profile scope for the schema-v1 scope contract, optionally with --scope "Domains/Product" for an applicable subtree. Add --profile research for schema-v1 research and nearest-routing obligations. Scoped runs inventory the whole vault before filtering results; sibling-only defects do not affect scoped status.

Scope topology changes go through the installed synchronizer. Preview before authorizing its exact content write set:

node /path/to/skills/validator/scripts/sync_scope_topology.js "/path/to/vault" --check
node /path/to/skills/validator/scripts/sync_scope_topology.js "/path/to/vault" --check --scope "Domains/Product"

Bases/Scope Registry.base and Agent/Scope Map.canvas are fully derived artifacts; the generated block in Agent/Scope Map.md is derived too. Do not edit them manually. Regenerate them with the synchronizer, which preserves user content outside managed checkpoint blocks. See the scope topology migration guide before adopting an existing vault.

A healthy vault reports all zeros:

yaml-ok
broken-wikilinks: 0
true-orphans-md: 0
unlinked-base-files: 0
bloat-warnings: 0
local-base-scope-warnings: 0
local-agents-inheritance-warnings: 0
ambiguous-wikilink-warnings: 0
scope-navigation-warnings: 0
routing-matrix-warnings: 0
base-scope-formula-warnings: 0
scope-adoption-warnings: 0
scope-contract-warnings: 0
scope-map-warnings: 0
research-boundary-warnings: 0
research-provenance-warnings: 0
provenance-cycle-warnings: 0
uncompiled-raw-source-warnings: 0
research-hub-warnings: 0

See docs/guides/validator.md for the full counter reference.

Guides

Global Discovery

After bootstrapping a vault, Ariadne can optionally register the vault on the user's machine. For existing vaults, use ariadne:global-discovery.

node skills/vault/scripts/register_vault.js \
  --vault "/path/to/vault" \
  --name "My Knowledge Vault" \
  --purpose "Long-term project and research knowledge." \
  --agents codex,claude,gemini \
  --primary

This creates ~/.ariadne/vaults.json and ~/.ariadne/vaults.md, then adds a small marker-managed discovery block to selected global agent instruction files. The block points agents to the registry; it does not copy the whole vault context.

Use this when you want future cold agent sessions, launched from any folder, to find the vault quickly for vague questions about prior projects, meetings, research, decisions, or "what was I working on?"

Use ariadne:workspace-instructions when a specific code repository or folder needs local AGENTS.md, CLAUDE.md, or GEMINI.md files that point back to registered Ariadne context. Hermes can use the canonical AGENTS.md directly; .hermes.md and HERMES.md are treated as explicit Hermes-specific overrides rather than default thin adapters. Workspace files should stay small; the vault remains the source of truth.

References

All reference docs live under skills/vault/references/:

Contributing

See CONTRIBUTING.md. Issues and PRs welcome — please read the contributing guide before opening either.

See PUBLIC_BOUNDARY.md for the public repository boundary and SECURITY.md for vulnerability reporting.

License

MIT