ariadne

Ariadne

Sensemaking for nonatomic entities using AI coding agents. Part of the SCADS program.

📖 Docs: https://ajbarea.github.io/ariadne/

Ariadne gave Theseus the thread that let him traverse the Labyrinth and find his way back out. This project is that thread: a single line of reasoning that traces one entity's evidence through a maze of heterogeneous data systems and back into a coherent analytic picture.

[!NOTE] Every architectural decision is grounded in current best-practice research, captured in docs/research/: new runtime dependencies and tools aren't adopted until grounded there with a # research(YYYY-MM): note. See ROADMAP.md.

The problem

Intelligence about a single entity (a person, a unit, an organizational node) is scattered across heterogeneous systems — graph databases, structured relational stores, and unstructured repositories — and across modalities — metadata, free text, imagery, and video. No single query interface spans that range. Analysts pivot manually between systems, losing context and momentum at every transition. The hard part isn't access; it's coherent, multi-hop reasoning across representations, where the decisive link between two facts may exist only through an implicit organizational relationship buried in a different store and a different modality.

The approach

Use an agentic AI harness — the Claude Agent SDK — as a unifying analytic interface, not a replacement for existing infrastructure. The harness is an orchestration layer that dispatches specialized tools and skills to retrieve, interpret, and synthesize across graph, structured, and unstructured sources in one coordinated workflow.

Central research question: given the harness and its UI, what specific tools, skills, and hooks are necessary to support a rigorous end-to-end analytic workflow targeting entities within an organizational hierarchy — and what is the minimum viable toolset that demonstrates real analytic value?

Deliverable

A working prototype that takes a target entity or organizational node as input and, through a coordinated sequence of tool invocations, surfaces relevant evidence from across all available data structures and modalities, synthesizing findings into a coherent analytic product. Success is measured by the harness's ability to:

• traverse organizational relationships,
• reconcile information across modalities,
• reduce the analyst's manual-pivot burden, and
• surface non-obvious connections impractical to find with conventional tooling.

SCADS umbrella role

Ariadne is conceived as an umbrella effort within SCADS. It does not duplicate sibling-project work; it defines integration interfaces so that contributions from other SCADS projects — graph-extraction pipelines, entity- resolution models, multimodal indexing schemes — can be surfaced as callable tools within the harness. It is both a standalone research contribution and a unifying demonstration layer for the SCADS portfolio.

Use from any AI CLI

The ariadne MCP server exposes the workup tool to any MCP client — Claude Code, Copilot, Gemini CLI, Cursor, Windsurf, and others. Two install paths:

Claude Code (one-click): add this repo's marketplace, then install the plugin:

/plugin marketplace add ajbarea/ariadne
# then: /plugin install ariadne

This bundles the MCP server (ariadne-mcp) + the analyst-workup skill into Claude Code in a single step. A workup is then available via the ariadne server tool.

Any other MCP client: add the server directly to the client's MCP config. From a local checkout (works now):

{
  "mcpServers": {
    "ariadne": { "command": "python", "args": ["-m", "ariadne.mcp_server"] }
  }
}

Once Ariadne is published to PyPI, the uvx form will also work:

{
  "mcpServers": {
    "ariadne": { "command": "uvx", "args": ["--from", "ariadne", "ariadne-mcp"] }
  }
}

Config caveat: the tool is portable; the data is not. Point the server at your stores (NEO4J_* / DATABASE_URI) and set ANTHROPIC_API_KEY per install. See ADR-0009.

Observability

Ariadne emits OpenTelemetry traces and metrics via the optional otel extra. The base install (api-only) is a no-op — nothing is emitted unless you configure an OTLP endpoint.

# 1. install the otel extra
uv sync --extra otel

# 2. point at your OTLP collector (Jaeger, Grafana, Datadog, etc.)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# 3. optionally add the Claude Agent SDK's per-LLM-call spans
export CLAUDE_CODE_ENABLE_TELEMETRY=1

What is emitted per workup: