Decision OS MCP

An MCP server for Decision OS — an LLM-native decision tracking and learning system.

What is Decision OS?

Decision OS captures novel pressure — moments when reality surprises you during engineering work. Unlike traditional documentation, it focuses on what an LLM couldn't predict, creating a learning loop:

``
Cases → Pressure Events (surprises) → Outcomes → Foundations (compressed learnings)
`

Quick Start

$3

`bash


Global install

npm install -g decision-os-mcp

Or use npx (no install needed)

npx decision-os-mcp
`

$3

Copy the template to your project:

`bash
cp -r templates/.decision-os /path/to/your-project/
`

Edit config.yaml with your project name.

$3

Add to your project's .cursor/mcp.json:

`json
{
"mcpServers": {
"decision-os": {
"command": "npx",
"args": ["-y", "decision-os-mcp"],
"env": {
"DECISION_OS_PATH": "${workspaceFolder}/.decision-os"
}
}
}
}
`

Copy the Cursor rules template:

`bash
cp templates/.cursor/rules/decision-os.mdc /path/to/your-project/.cursor/rules/
`

Tools

| Tool | Description |
|------|-------------|
| get_context | Get active case, recent pressures, foundations ranked by relevance, conflicts |
| log_pressure | Log a pressure event when reality differs from expectation |
| quick_pressure | Quick-capture a pressure event with minimal friction (only expected + actual required) |
| create_case | Create a new case (unit of work) |
| close_case | Close a case with outcome signals and regret score (auto-forgets successful cases) |
| set_active_case | Set the active case for the session (persists across restarts) |
| get_foundations | Query foundations from project and global scopes |
| search_pressures | Search past pressure events |
| check_policy | Check what policy requires for given signals |
| promote_to_foundation | Promote pressure events to a foundation (PROJECT or GLOBAL scope) |
| elevate_foundation | Elevate a project foundation to global scope |
| validate_foundation | Validate that a global foundation applies in current project |
| suggest_review | Review project for unextracted learnings and forgetting opportunities |
| list_cases | List all cases in the project |

Core Concepts

$3

The primary learning artifact. Logged when something unexpected happens:

`yaml
expected: "Supabase insert would throw on null FK"
actual: "RLS silently blocked the write, no error"
adaptation: "Added explicit null-check before insert"
remember: "Supabase RLS fails silently on null FK values"
`

$3

Compressed learnings promoted from repeated pressure events:

`yaml
id: F-0001
title: "Supabase RLS fails silently on null FK"
default_behavior: "Always validate FK values before insert when using RLS"
context_tags: [SUPABASE, RLS, DATA_MODEL]
confidence: 2 # Out of 3
scope: PROJECT # or GLOBAL
origin_project: my-project
validated_in: [my-project, other-project]
exit_criteria: "Supabase adds explicit error for null FK violations"
source_pressures: [PE-0003, PE-0007]
`

$3

Decision OS supports a cascading scope model similar to Git config:

`
~/.decision-os/ # GLOBAL (user-wide, universal learnings)
├── config.yaml
└── defaults/foundations.yaml # GF-prefixed foundations

~/projects/my-app/.decision-os/ # PROJECT (specific to this codebase)
├── config.yaml
├── cases/
└── defaults/foundations.yaml # F-prefixed foundations
`

Resolution order: PROJECT wins over GLOBAL on conflicts.

Global foundations are recommendations, not rules. They represent universal patterns that transcend specific tech stacks:
- Tool behaviors (e.g., "MCP descriptor paths may be stale")
- Debugging strategies (e.g., "Trace call sites before refactoring")
- Meta-learnings (e.g., "Question requirements before implementing")

Setup global foundations:

`bash


Create global .decision-os


mkdir -p ~/.decision-os/defaults
cp templates/global-.decision-os/config.yaml ~/.decision-os/
cp templates/global-.decision-os/defaults/foundations.yaml ~/.decision-os/defaults/
`

Conflict detection: When get_context is called, it highlights conflicts where project and global foundations overlap or contradict each other.

$3

Bounded units of work (feature, bugfix, spike) that provide context for pressure events:

`yaml
id: 0001-add-tile-caching
title: "Add tile caching"
goal: "Reduce API latency for repeated tile requests"
status: ACTIVE
signals:
context:
risk_level: MEDIUM
affected_surface: [PERFORMANCE_CRITICAL, INTEGRATION]
decisions:
approach: BUILD
posture: BALANCED
validation_level: STANDARD
`

Directory Structure

`


Global (user-wide)

~/.decision-os/
├── config.yaml # scope: GLOBAL
└── defaults/
└── foundations.yaml # GF-prefixed universal learnings

Project (per-codebase)

your-project/
├── .decision-os/
│ ├── config.yaml # scope: PROJECT
│ ├── cases/
│ │ ├── 0001-bootstrap/
│ │ │ ├── case.yaml # Case metadata
│ │ │ └── pressures.yaml # Pressure events
│ │ └── 0002-add-auth/
│ │ └── ...
│ └── defaults/
│ └── foundations.yaml # F-prefixed project learnings
├── .cursor/
│ ├── mcp.json # MCP server config
│ └── rules/
│ └── decision-os.mdc # LLM instructions
└── src/
`

LLM Workflow

1. At task start: Call get_context() to load active case and foundations (ranked by relevance)
2. When surprised: Call quick_pressure() for fast capture or log_pressure() for full detail
3. Before BUILD decisions: Call check_policy() to see requirements
4. At task end: Call close_case() with regret score
5. Periodically: Call suggest_review() to find unextracted learnings and forgetting opportunities

Forgetting

The system forgets by design. Cases are temporary containers — knowledge lives in foundations.

When close_case() is called with regret 0 and there are no unpromoted pressure events, the case is automatically deleted. Not archived. Forgotten.

This keeps the .decision-os/cases/ directory lean: only cases that still have uncompressed learning (unpromoted PEs or regret 1+) survive.

The lifecycle:
1. Cases are born when work starts
2. Pressure events are captured when surprises happen
3. PEs are promoted to foundations when patterns emerge
4. Cases are forgotten when they have nothing left to teach
5. Foundations survive as the only persistent knowledge

Use suggest_review() to find cases blocking forgetting (regret 0 but unpromoted PEs remain) and decide whether to promote or discard them.

Active Case Persistence

The active case is persisted to .decision-os/.active-case and survives MCP server restarts. No more losing your active case when Cursor restarts.

Signals Vocabulary

$3


- risk_level: LOW / MEDIUM / HIGH
- reversibility: EASY / MEDIUM / HARD
- change_frequency: RARE / OCCASIONAL / FREQUENT
- affected_surface: CORE_DOMAIN / INTEGRATION / DATA_MODEL / INFRA_DEPLOY / SECURITY_BOUNDARY / UI_UX / PERFORMANCE_CRITICAL
- novelty: LOW / MEDIUM / HIGH

$3

- approach: REUSE / REFRAME / BUILD / HYBRID
- posture: MINIMAL / BALANCED / ROBUST
- validation_level: BASIC / STANDARD / STRICT

$3

- regret: 0-3 (0 = would choose same, 3 = strong regret)
- regressions: NONE / MINOR / MAJOR

Development

`bash


Install dependencies

npm install

Build

npm run build

Run locally

DECISION_OS_PATH=/path/to/.decision-os npm start
``

Philosophy

- Log only novel pressure: Don't document what an LLM could derive
- The system should forget: Successful cases are deleted. Knowledge lives in foundations, not cases
- Hypotheses, not axioms: Foundations have confidence and can be revised
- Minimal ceremony: Small vocabulary, structured but not bureaucratic
- Capture first, filter later: When unsure, log it — capturing too much is better than missing surprises
- LLM-native: Designed for AI-assisted engineering workflows

License

MIT