SPB Git

Repository Public Research preview

README.md 7.0 KB 128 lines markdown

1# research-ledger-mcp23An MCP server that keeps the record of a preregistered study: what was hypothesised, what was fixed in advance, what was decided and when, what departed from the plan, what was run, what it cost, and what came out.45It is offline and deterministic. It never uses the network, never runs a command, and writes only inside `.research/` in the project root.67## Why89An agent that runs a study over several sessions forgets. It re-runs the costly step, tunes the specification after seeing the result, and reports the outcome as if it had been predicted. This server gives it a place to write things down that it cannot quietly rewrite, and derives the label "confirmatory" or "exploratory" from the timeline instead of taking anyone's word for it.1011## Install1213Requires Node.js 20 or later.1415```bash16npm install17```1819Claude Code:2021```bash22claude mcp add research-ledger --env RESEARCH_LEDGER_ROOT=/path/to/project -- node /path/to/research-ledger-mcp/server.mjs23```2425Any MCP client (stdio):2627```json28{29  "mcpServers": {30    "research-ledger": {31      "command": "node",32      "args": ["/path/to/research-ledger-mcp/server.mjs"],33      "env": { "RESEARCH_LEDGER_ROOT": "/path/to/project" }34    }35  }36}37```3839| Variable | Meaning |40|---|---|41| `RESEARCH_LEDGER_ROOT` | Project root. Default: the working directory of the server. Every file path given to a tool must resolve inside it. |4243## Tools4445| Tool | What it does |46|---|---|47| `init_project` | Create the ledger (once), with an optional budget |48| `register_hypothesis` | Record a hypothesis with its test and decision rule |49| `freeze_protocol` | Hash the protocol files and hypotheses into one root hash; refuses to freeze twice |50| `verify_protocol` | Re-hash the frozen files; report which changed, went missing or were renamed |51| `amend_protocol` | New linked protocol version, with the reason and whether data had been seen |52| `mark_data_access` | Record when outcome data are first opened |53| `log_decision` | Question, options, choice, rationale, before or after data (`D-01`, `D-02`…) |54| `log_deviation` | Protocol said / done / why / impact on confirmatory status (`V-01`…) |55| `open_gate`, `close_gate` | Go / no-go / conditional review, criteria recorded before evidence |56| `check_rerun` | Is an identical run already on record, and was it expensive? |57| `register_run` | Command, hashes of code, inputs and outputs, seed, environment (`R-01`…) |58| `record_spend`, `spend_report`, `set_budget` | Cost of paid calls, exact totals, budget remaining |59| `record_result` | Estimate, uncertainty, verdict; status derived by the ledger (`X-01`…) |60| `log_question`, `resolve_question` | Open questions carried across sessions |61| `status` | Everything needed to resume |62| `export_report` | Transparency report, Markdown and JSON |63| `verify_ledger` | Re-compute the hash chain; pinpoint the first broken record |6465## How a result gets its status6667`record_result` never asks whether a result is confirmatory. It works it out:6869| Situation | Status |70|---|---|71| Hypothesis fixed by a protocol version frozen before outcome data; files intact; no deviation | `confirmatory` |72| Same, with deviations declared `minor` | `confirmatory_with_deviations` |73| No freeze before the result | `exploratory` |74| First freeze made after outcome data were accessed | `exploratory` |75| Hypothesis registered after the last pre-data protocol version | `exploratory` |76| Protocol amended after data were seen, for this hypothesis | `exploratory` (results recorded after the amendment) |77| A deviation declared `exploratory` applies | `exploratory` |78| Frozen files differ from the manifest when the result is recorded | `exploratory` |7980Outcome data count as accessed from the first of: a `mark_data_access` record with `outcome_data` true, an amendment declared with `data_seen` true, or any recorded result.8182## Storage8384```85.research/86  ledger.jsonl      one JSON record per line, append-only87  HEAD              sequence number and hash of the last record88  lock              present only while a record is being appended89  reports/          written by export_report with write: true90```9192Each record is `{seq, ts, type, data, prev, hash}`. `hash` is the SHA-256 of the canonical JSON (sorted keys) of the other five fields; `prev` is the hash of the record before.9394- **Atomic writes.** The ledger is written to a temporary file, flushed to disk, then renamed over the old one. A writer that dies leaves either the old ledger or the new one, never half a record.95- **Locking.** Appends are serialised by an exclusive lock file. Numbers (`D-01`, `R-01`…) are assigned inside the lock, so concurrent writers never receive the same one. A lock older than 30 seconds is treated as abandoned.96- **Corruption stops writes.** If verification fails, every tool that appends refuses, and says at which record the chain broke.9798## What the chain proves, and what it does not99100It detects a record that was edited, deleted, inserted, reordered or cut off, and reports the first affected line. The freeze manifest detects any change to a listed file.101102It does not stop someone with write access from rebuilding the whole chain and `HEAD` from scratch: there is no secret key and no outside witness. If you need to prove to someone else what was fixed and when, copy the root hash returned by `freeze_protocol` (and, later, the head hash from `verify_ledger`) somewhere you do not control alone: a commit on a remote, a registry entry, a dated message.103104Other limits to know:105106- Timestamps are the local clock of the machine. They are part of each hash but are not independently attested.107- The server records what it is told. `register_run` hashes the files you list at the moment you call it; it does not execute or observe the run. `mark_data_access`, `timing` and `data_seen` are declarations. The ledger catches contradictions with its own timeline, not what was never written.108- "Renamed" detection looks for identical content in the same directory only.109- Costs are stored in millionths of a US dollar. One currency.110- The whole ledger is rewritten on each append (that is what makes the write atomic). This suits thousands of records, not millions.111- The lock is advisory and local: it does not coordinate writers on a network file system that lacks exclusive create.112113## Permissions114115The server reads the files you list (to hash them) and writes inside `.research/`. It starts no process and opens no connection. The manifest declares `shell` only because the client launches it with `node` and the test suite starts worker processes to test concurrent writers.116117## Tests118119```bash120npm test121```12212349 engine tests and 8 protocol tests, all offline, in temporary directories. They cover every tool, tampering (edited, deleted, inserted, swapped and truncated records), one-byte and renamed-file detection, refusal to refreeze, numbering under six concurrent writers, the expensive-run guard, exact spend arithmetic, status classification including an amendment after data, two simulated crashes during a write, and path confinement including symbolic links.124125## Licence126127MIT128
Files main
Menu

Theme