decisiontrail

decisiontrail is a local decision memory for coding agents. When an agent makes a call — which database, which cache, which release cadence — decisiontrail records the decision together with the limits it was made under, so a later session can find the precedent instead of re-deciding from scratch, and can revise it explicitly when the call changes.

Everything is local: decisions live in one JSON file on your machine. There is no account, no login, and no network access. Records can be plain commits or validated decision records (constraints, evidence and an answer); validated records are the ones precedent search draws on. Old decisions are never edited in place — a revision creates a new record and marks the old one superseded, linked in both directions.

This package is a clean-room rebuild of the local surface of the "elen" MCP server (10 of its 12 tools). The original's two connected-mode beta tools, elen_incoming and elen_team_search, need a hosted workspace, a login and an API key, and are not included.

Install

npx @reneturcios/decisiontrail elen_status

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/decisiontrail

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead. If you run the container, mount a volume over the store directory if you want decisions to persist.

Related MCP server: horizon-ledger

Where decisions live

• Store path: the DECISIONTRAIL_DB environment variable, or ~/.decisiontrail/decisions.json by default.

• The file is a single JSON document. A missing file starts empty; writes are atomic (temp file, then rename), so a crash mid-write cannot truncate the store.

• DECISIONTRAIL_AGENT and DECISIONTRAIL_PROJECT name the namespace reported by elen_status; both default to local.

Decision IDs are sequential: d-1, d-2, … in creation order.

CLI

One bin serves both faces. Each tool is a subcommand taking a single JSON argument (optional for the no-argument tools); results print as JSON.

# Check the namespace before committing
decisiontrail elen_status

# Commit a decision with its limits
decisiontrail elen_commit '{"text":"Use Postgres for sessions","constraints":["must be durable"],"domain":"storage"}'

# Record a validated decision
decisiontrail elen_log_decision '{"constraints":["latency under 100ms"],"evidence":["benchmark run 42"],"answer":"Adopt the in-process cache","domain":"performance"}'

# Before a new decision, ask for pointers; then search validated precedents
decisiontrail elen_suggest '{"query":"session storage"}'
decisiontrail elen_search_precedents '{"query":"session storage"}'

# Read one record in full, revise one, survey the store
decisiontrail elen_expand '{"id":"d-1"}'
decisiontrail elen_supersede '{"id":"d-1","text":"Use Redis for sessions with Postgres fallback"}'
decisiontrail elen_get_context
decisiontrail elen_get_competency
decisiontrail elen_consolidate

decisiontrail --version

Exit codes: 0 on success, 1 for a domain error (for example an unknown decision ID — the error names the ID), 2 for usage errors and invalid arguments.

MCP server

npx -y @reneturcios/decisiontrail mcp

MCP client configuration:

{
  "mcpServers": {
    "decisiontrail": {
      "command": "npx",
      "args": ["-y", "@reneturcios/decisiontrail", "mcp"]
    }
  }
}

Tools

How matching works

elen_suggest and elen_search_precedents rank by case-insensitive token overlap between the query and a record's text plus constraints: the score is the number of distinct query tokens present. Records with no overlap are omitted; ties are broken by recency, newest first.

A record counts as validated only when it was created with elen_log_decision. A committed decision that is later superseded keeps its history: supersedes / superseded_by link the chain and the old record's status becomes superseded.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, temp dirs, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.