# DAiMON

[![tests](https://github.com/ARIES-photonics/daimon/actions/workflows/tests.yml/badge.svg)](https://github.com/ARIES-photonics/daimon/actions/workflows/tests.yml)

**Your AI proposes the approach you already ruled out. DAiMON stops it and shows you why you killed it.**

You test something, it fails for a specific reason, you write the reason down and move on. Four
months later your assistant suggests it again, confidently, because every session starts cold and
your verdict is sitting in a transcript nothing can query. You either remember and correct it, which
costs you the interruption, or you don't, and you pay for the same dead end twice.

DAiMON is a ledger of what you ruled out, and a gate in front of it. It runs locally as an MCP
server. Your decisions never leave your machine.

[Source](https://github.com/ARIES-photonics/daimon) · [Tests](tests/) · [Benchmarks](benchmarks/) · [License](LICENSE)

## The rule

Every proposed action gets one of five levels. Only the top one stops anything.

| Level | Meaning |
|---|---|
| 5 CLEAR | Nothing matches. Proceed, no citation needed. |
| 4 NOTE | Prior evidence exists nearby. Noted, no interruption. |
| 3 CAUTION | Related to ruled-out work. Proceed, but say what is new. |
| 2 WARNING | Looks like a redo. Name the missing new constraint first. |
| 1 HARD ALERT | Same test, same method, same claim, nothing new. Stop, here is the prior verdict. |

A hard alert requires all of: same test, redo intent, same method, same claim, no new premise, and
not a hedged or diagnostic question. Asking "check what failed here first" is someone being careful,
not someone redoing. The rule is deterministic, first match wins, no tunable thresholds, and it
lives in `daimon_mcp/gamut.py` in the open so you can see exactly when it fires.

Four of the five levels inform and get out of the way. A guard that blocks everything gets switched
off in a week.

## It never blames you

Nobody asks to redo failed work on purpose. They ask because they never saw the verdict. DAiMON says
"you may not have seen this, here is the prior ruling." It does not call anything wasteful, and a
human always makes the final call.

## Tools

- `daimon_check_action(action)` check a proposed action, get the level, the prior verdict, and a
  `check_id` receipt proving the action was looked at
- `daimon_add_decision(claim, reason, reopen_only_if, tags)` record a ruling
- `daimon_list_decisions()` everything DAiMON is guarding against
- `daimon_add_correction` / `daimon_check_correction` the same guard for instruction compliance and
  response shape, catching drift like "you were asked for verbatim text and wrapped it in commentary"
- `daimon_audit_session(session_id)` which actions were taken without ever being checked

`reopen_only_if` matters more than it looks. A ledger that only says no is a wall. This one tells you
where the door is.

## Install

```sh
git clone https://github.com/ARIES-photonics/daimon.git
cd daimon
python3 -m pip install -e .
```

**Claude Desktop.** One entry in your MCP config, then restart:

```json
"daimon": { "command": "python3", "args": ["-m", "daimon_mcp.mcp_server"] }
```

There is no bundled runtime, so it uses the Python already on your machine. If yours came from
Anaconda, point it at that interpreter.

**ChatGPT.** ChatGPT connects over remote HTTPS and has no stdio transport, so it needs the included
proxy and tunnel:

```sh
bash add_chatgpt.sh          # prints the connector URL
bash add_chatgpt.sh status
bash add_chatgpt.sh stop
```

This runs an internal service on loopback that holds the ledger, a redacted public proxy that holds
nothing, and a cloudflared tunnel. **The ledger never faces the internet.** ChatGPT receives only the
level and an approved summary. Requires `cloudflared`.

Verify either client by asking it to "rerun detector v2 on the baseline pipeline, same settings".
The correct response is a hard alert.

## Tests and benchmarks

```sh
PYTHONWARNINGS=error python3 -m unittest discover -s tests -q
python3 -m benchmarks.decision_index_benchmark
```

The current suite contains 211 tests across 26 test modules covering retrieval, escalation, false
negatives, sycophancy, redaction, receipts, ledger schema repair, and hot-cache behavior. Nine
benchmark programs and their dated result reports are checked in, so you can inspect what was
measured and when rather than taking a claim on trust.

## What this is not

Not a memory system and not a RAG index. It does one thing: it matches a proposed action against
rulings you made deliberately, and grades the overlap. It has no opinion about anything you have not
ruled out.

## License

AGPL-3.0. Use it, fork it, run it, modify it, sell it. The one condition is that if you modify DAiMON
and offer it to others over a network, your modifications have to be published too.

That condition is the point. Everything here was built on work other people made available. What you
build on top stays available to whoever comes next.

Copyright 2026 Liam D. Sparling