Decision OS

You deploy and run the Decision OS MCP Server to capture, organize, and propagate learning from unexpected events during engineering work. This server pairs with a client you run in your project, enabling you to log pressure events, create cases, and promote repeated learnings into foundational patterns that persist across projects and codebases.

How to use

You interact with the MCP server through a client integrated in your development workflow. Start by installing the MCP client, then connect it to your project’s local decision space. Use the client to load your current active case, log pressures when reality diverges from your expectations, and review outcomes that guide future work. At the end of a task, close the active case with an outcome signal so the system can promote repeated learnings into foundations or forget insights that no longer apply.

How to install

Prerequisites: you need Node.js and npm installed on your machine. You will either install the MCP server CLI globally or run it via a package runner.

# Global install
npm install -g decision-os-mcp

# Or use npx (no install needed)
npx decision-os-mcp

Additional configuration and usage notes

Add the MCP server to your project to enable local coordination of decisions and learnings. Copy the template to your project and customize the configuration file with your project name.

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

Edit config.yaml with your project name.

## Cursor integration

Configure your project’s Cursor to connect to the MCP server. The example below shows how to point the cursor at the MCP CLI using an environment path for your project data.

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

## Tools you can use

You have access to a set of tools to manage cases, pressures, and foundations. Use them to retrieve context, log surprises, create and close cases, promote learnings, and review project readiness.

## Core concepts at a glance

Key artifacts include Pressure Events, which capture surprises; Foundations, which compress and preserve learnings; and Cases, which group related pressures during work. Learnings cascade from cases to foundations and can be scoped globally or per project.

## Active case persistence and forgetting rules

The active case is kept in your project folder and persists across MCP restarts. The system forgets by design: when you close a case with zero regret and there are no unpromoted pressure events, the case is removed. Foundations survive as the persistent knowledge.

## Signals vocabulary

Context signals, decisions, and outcome signals define the language for describing risks, approaches, and results. Use them to structure your entries and ensure consistent learning across cases.

## Development and philosophy

The MCP server is designed to log only novel pressures, support forgetting of outdated cases, and promote hypotheses into revisable foundations. It emphasizes minimal ceremony and a focus on AI-assisted engineering workflows.

## License

MIT licensed.

## Available tools

### get\_context

Retrieve the active case, recent pressures, and ranked foundations to inform current work.

### log\_pressure

Record a pressure event when reality diverges from expectation to capture learning.

### quick\_pressure

Capture a pressure with minimal input, focusing on expected vs actual.

### create\_case

Create a new case to group related work and pressures.

### close\_case

Close the active case and provide outcome signals and regret score.

### set\_active\_case

Set or switch the active case for the session.

### get\_foundations

Query foundational learnings across project and global scopes.

### search\_pressures

Search past pressure events for reference and pattern discovery.

### check\_policy

Check required policy for given signals before proceeding.

### promote\_to\_foundation

Promote pressure events to a foundation at PROJECT or GLOBAL scope.

### elevate\_foundation

Move a project foundation to global scope.

### validate\_foundation

Validate that a global foundation applies to the current project.

### suggest\_review

Suggest reviews to identify unextracted learnings and forgetting opportunities.

### list\_cases

List all cases within the project.