Incident Investigator

Incident Investigator

LLMs collect evidence. Incident Investigator conducts investigations.

        Claude / Codex
              │
              ▼
      Collect Evidence
              │
              ▼
   Incident Investigator
   ├── Protocol
   ├── Questions
   ├── Investigation Graph
   ├── Reasoners
   └── Intelligence
              │
              ▼
    Structured Findings
              │
              ▼
        Claude / Codex

An open-source investigation runtime (MCP server). Not an AI agent—a stateful engine that turns vendor-neutral evidence into hypotheses, confidence, and explainable conclusions.

The assistant gathers from Datadog, Kubernetes, logs, or anywhere else. The runtime owns the investigation: what to ask next, what you still need, when you can conclude, and why.

No connectors in core. Evidence categories in; structured findings out.

Quick start

go install github.com/stackrail/incident-investigator/cmd/incident-investigator@latest

Wire it as an MCP server in Claude Code, Codex, or Cursor → [plugins/incident-investigator/](plugins/incident-investigator/).

Persistence (optional)

By default investigations live in memory for the process lifetime. For durable storage across restarts:

export II_PERSISTENCE_TYPE=sqlite
export II_PERSISTENCE_PATH=~/.incident-investigator/runtime.db
incident-investigator

Docker Compose and the plugin Docker launcher configure SQLite automatically. See [docs/persistence.md](docs/persistence.md).

MCP tools

The server exposes 34 MCP tools over stdio. Run incident-investigator help for the full list.

| Category | Tools | | --- | --- | | Investigation | start_investigation, submit_evidence, get_investigation_status, finish_investigation | | Protocol | get_investigation_plan, list_open_questions, resolve_question, explain_investigation | | Reasoning | explain_reasoning, get_reasoning_cycles | | Graph | get_graph, query_graph, get_subgraph, explain_path | | Intelligence | find_similar_investigations, suggest_patterns, calibrate_confidence | | Persistence | list_investigations, resume_investigation, archive_investigation, delete_investigation, export_investigation, import_investigation | | Resolution | generate_resolution, get_resolution, export_resolution, list_resolutions, update_resolution_status, get_resolution_metrics | | Publishing | publish_resolution, list_publish_history, retry_failed_publishes, list_dead_letter_publishes, retry_dead_letter_publish |

Persistence and resolution data survive process restarts when II_PERSISTENCE_TYPE=sqlite is set. Publish history and dead-letter records use the same SQLite database when publishing is enabled (II_PUBLISH_ENABLED=true). With the default in-memory backend, recovery and resolution tools still work for the lifetime of the server process; publish audit state is ephemeral until SQLite persistence is configured. See [docs/persistence.md](docs/persistence.md) and [docs/resolution-engine.md](docs/resolution-engine.md).

Completed investigations are indexed for intelligence similarity on finish_investigation, archive_investigation (when completed), and server startup (from persisted outcomes).

git clone https://github.com/stackrail-io/Incident-Investigator.git && cd Incident-Investigator
go test ./...

Documentation

| | | | --- | --- | | [docs/README.md](docs/README.md) | Documentation index | | [Philosophy](docs/philosophy.md) | Why the project exists | | [Architecture](docs/architecture.md) | How it fits together | | [Development](docs/development.md) | Extend reasoners, archetypes, playbooks | | [Persistence](docs/persistence.md) | Durable storage, recovery MCP tools, export/import | | [Resolution Engine](docs/resolution-engine.md) | Action items and lessons from completed investigations | | [Specification](spec/investigation-v1/SPECIFICATION.md) | Portable protocol contract | | [Examples](examples/) | Seven replayable investigations |

Contributing

[CONTRIBUTING.md](CONTRIBUTING.md) · [ROADMAP.md](ROADMAP.md)

License

MIT — [LICENSE](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stackrail-io
• Source: stackrail-io/Incident-Investigator
• License: MIT
• Homepage: https://stackrail.io/

Install and usage instructions live in the source repository linked above.