@triedotdev/mcp 1.0.169 → 1.0.170

package/README.md

@@ -1,602 +1,111 @@
-# Trie: Governance ledger for agent-human teams
+# Trie Agent
 
-**Context that travels from Agents → CLI → CI/CD, keeping agents and humans aligned.**
+**Cloud context bridge for Cursor and Claude Code.** Connects AI assistants to your Trie cloud workspace—signals, documents, ledger, and graph—so agents have the right context before editing.
 
 [![Download Workspace](https://img.shields.io/badge/Download-Trie%20Workspace-blue)](https://www.trie.dev) [![Follow on X](https://img.shields.io/badge/Follow-@louiskishfy-1DA1F2?logo=x)](https://x.com/louiskishfy)
 
-## The Problem
-
-When agents and humans ship code together across Cursor, Claude Code, VS Code, and CI/CD, context fragments. An agent makes a decision in one tool, a human forgets it in another, and nothing prevents repeating the same mistake.
-
-**Traditional tools don't solve this:**
-- Linear tracks tasks, not decisions or reasoning
-- GitHub shows changes, not why they were made
-- Slack/Discord: context vanishes in chat history
-- No tool tells you if today's change conflicts with yesterday's decision
-
-## The Solution
-
-Trie keeps a **governance ledger**—a tamper-evident record of decisions, incidents, and fixes that travels with your code. Every tool reads from the same ledger, so decisions persist and everyone stays aligned.
-
-- **`trie watch`** - Monitors your codebase 24/7, learns patterns autonomously
-- **`trie gotcha`** - Predicts problems before you ship based on past incidents
-- **Governance ledger** - Decision memory with Git-backed audit trail and digital signatures
-- **Cross-tool context** - Same ledger in Cursor, CLI, CI/CD—no coordination needed
-
-Think of it as **double-entry bookkeeping for code decisions**—tamper-evident accountability that works with Git and your existing workflow.
-
 ## Quick Start
 
 ### Install
 
 ```bash
-npm install -g trie
-cd your-project
-trie init
-```
-
-### Basic Workflow
-
-```bash
-# 1. Report incidents as they happen
-trie tell "Users can't log in after password reset"
-
-# 2. Start autonomous monitoring
-trie watch
-
-# 3. Before pushing, check for risks
-trie gotcha
-
-# 4. Learn from your git history
-trie learn
-
-# 5. Give feedback
-trie ok    # Prediction was helpful
-trie bad   # Prediction was wrong
-```
-
-## Core Features
-
-### 1. Autonomous Monitoring (`trie watch`)
-
-Real-time agent that monitors your codebase and enforces custom rules:
-
-```bash
-# Set any quality rule you want enforced
-trie goal add "No console.log statements in production"
-trie goal add "All API endpoints must have rate limiting"
-trie goal add "We never truncate text in UI components"
-
-# Start watching
-trie watch
+npm install -g @triedotdev/mcp
 ```
 
-**Features:**
-- **Interactive dashboard** with goals, memory, and analysis activity
-- **AI-powered goal checking** using semantic understanding (not just keywords)
-- **AI-powered Gotcha Prediction** - Automatically analyzes changed files for potential problems using Claude
-- **AI-powered Learning** - Learns from git history (fix/revert commits) every 10 file changes
-- **Signal extraction** - Extracts governance decisions, facts, and blockers from code changes
-- **Token-aware** to manage AI costs
-- **Smart caching** to avoid duplicate scans
-- **Real-time nudges** when violations are detected
-
-**How AI integration works in watch mode:**
-1. When files change, AI extracts structured signals (governance, facts, blockers)
-2. Gotcha Predictor analyzes changes for potential problems using Claude Sonnet 4
-3. Learning Engine periodically learns from git history to improve predictions
-4. All findings are stored in the governance ledger for future reference
+### Login
 
-Run in background with screen or tmux:
 ```bash
-screen -S trie-watch
-trie watch
-# Detach: Ctrl+A then D
-# Reattach: screen -r trie-watch
+trie login
 ```
 
-### 2. AI-Powered Predictive Analysis (`trie gotcha`)
-
-Uses Claude (Anthropic) to predict problems before you ship, combining:
-- **AI code analysis** - Semantic understanding of bugs, security issues, and anti-patterns
-- **Governance context** - Relevant decisions and blockers from the ledger
-- **Historical incidents** - Past regressions in the same files
-- **Active tickets** - Linear tickets that might conflict
-
-```bash
-# Check current changes for risks (requires ANTHROPIC_API_KEY)
-trie gotcha
-
-# Connect to Linear for JIT defect prediction
-trie linear auth <your-api-key>
-trie linear sync
-```
-
-**How it works:**
-1. Analyzes changed files with Claude Sonnet 4
-2. Checks against governance decisions and active blockers
-3. Searches for similar past incidents
-4. Returns structured predictions with risk levels and recommendations
-5. Falls back gracefully if AI unavailable
-
-### 3. Governance Ledger
-
-Tamper-evident record of all decisions, incidents, and fixes:
-
-**Architecture:**
-- **Governance ledger** (`.trie/memory/ledger.json`) - Append-only chain with Ed25519 signatures
-- **Issue memory** (`.trie/memory/issues.json`) - Fast searchable cache
-
-**Key properties:**
-- Never deleted, only corrected (full audit trail)
-- Digital signatures prove who (human or agent) created each entry
-- Auto-commits to Git for distributed backup
-- Works across Cursor, CLI, CI/CD—same ledger everywhere
-
-**Setup signing:**
-```bash
-trie keys generate    # Generate Ed25519 signing key
-trie keys status      # Check if signing is configured
-```
-
-**Ledger commands:**
-```bash
-trie ledger verify    # Validate chain integrity
-trie ledger history   # Show blocks with author attribution
-trie ledger stats     # Block counts, entries, severity breakdown
-```
-
-**Corrections (not deletions):**
-```bash
-# Mark false positive
-trie ledger correct <entry-id> -r "Expected behavior" -t false-positive
-
-# Mark as fixed
-trie ledger correct <entry-id> -r "Fixed in commit abc123"
-
-# View correction stats
-trie ledger corrections
-```
-
-## Integrations
-
-| Integration | Setup | Purpose |
-|-------------|-------|---------|
-| **Linear** | `trie linear auth <key>` | JIT defect prediction from active tickets |
-| **GitHub** | Set `GITHUB_TOKEN` env var | Sync PRs and issues into context graph |
-| **Slack** | `trie setup slack <webhook>` | Team notifications for critical issues |
-| **Cursor Cloud** | Set `CURSOR_API_KEY` | Verified automated fixes via cloud agent |
+This opens a browser to authorize the CLI with your Trie account. After login, the MCP server can access your team's cloud context.
 
-### Linear Integration
+### MCP Setup (Cursor / Claude Code)
 
-```bash
-trie linear auth <your-api-key>
-trie linear sync
-```
-
-Or via MCP: `trie_linear_sync` — syncs tickets into the context graph for gotcha predictions.
-
-### GitHub Integration
-
-Sync open PRs and issues into the context graph:
-
-```bash
-# Via MCP (Cursor/Claude)
-trie_github_sync
-trie_github_branches  # See which branch has latest updates
-```
-
-Requires `GITHUB_TOKEN` (repo scope for private repos, public_repo for public).
-
-### Slack Integration
-
-```bash
-# Show setup guide
-trie setup slack
-
-# Configure webhook
-trie setup slack <webhook-url> [#channel]
-
-# Test connection
-trie setup test-slack
-```
+Add to your MCP settings:
 
-Or manually add to `.trie/config.json`:
 ```json
 {
-  "integrations": {
-    "slack": {
-      "enabled": true,
-      "webhook": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
-      "channel": "#security"
+  "mcpServers": {
+    "trie": {
+      "command": "trie",
+      "args": ["mcp"],
+      "env": {}
     }
   }
 }
 ```
 
-### Cursor Cloud Agent
-
-Dispatch high-risk issues to Cursor's cloud for verified, test-passing fixes:
-
-```bash
-# Via MCP
-trie_cloud_fix action:configure apiKey:"key-..."
-trie_cloud_fix action:dispatch issueIds:["issue-1"]
-
-# Force cloud dispatch (bypass triage)
-trie_cloud_fix action:dispatch forceCloud:true
-
-# Ad-hoc dispatch
-trie_cloud_fix action:dispatch file:"src/auth.ts" issue:"SQL injection" fix:"Use parameterized queries"
-```
-
-The cloud agent runs in an isolated VM, applies the fix, runs tests, captures screenshots, and opens a PR.
-
-### Pipeline View
-
-See work across Linear, GitHub, and Trie in one place:
-
-```bash
-# Via MCP
-trie_pipeline                    # Full status: tickets, PRs, issues
-trie_pipeline action:coverage    # Only Trie issues with no ticket/PR
-trie_pipeline action:create_tickets issueIds:["id1","id2"]  # Open tickets
-```
-
-## AI Tool Integration (MCP)
-
-Trie provides Model Context Protocol tools for Claude, Cursor, and AI assistants.
-
-### Setup for Cursor/Claude
-
-Add to your MCP settings:
+If you use `npx` instead of a global install:
 
 ```json
 {
   "mcpServers": {
     "trie": {
-      "command": "trie",
-      "args": ["mcp"],
-      "env": {
-        "ANTHROPIC_API_KEY": "your-api-key",
-        "LINEAR_API_KEY": "your-key",
-        "GITHUB_TOKEN": "your-token",
-        "CURSOR_API_KEY": "your-cursor-key"
-      }
+      "command": "npx",
+      "args": ["-y", "@triedotdev/mcp", "mcp"],
+      "env": {}
     }
   }
 }
 ```
 
-### Available Tools
-
-**Core:**
-- `trie_tell` - Report incidents and extract structured signals
-- `trie_check` - Quick risk assessment
-- `trie_watch` - Start/stop autonomous monitoring
-- `trie_memory` - Search incident history
-- `trie_fix` - Apply fixes (use `action:route` to see triage plan)
-- `trie_cloud_fix` - Dispatch to Cursor cloud agent
-
-**Integrations:**
-- `trie_linear_sync` - Sync active Linear tickets
-- `trie_github_sync` - Sync open PRs and issues
-- `trie_github_branches` - Fetch branches with latest commits
-- `trie_pipeline` - Consolidated view of tickets, PRs, issues
-
-**Query Tools (Targeted Context):**
-- `trie_get_governance` - Query decisions with filters
-- `trie_get_blockers` - Get active blockers only
-- `trie_get_nudges` - Get unresolved goal violations
-- `trie_get_related_governance` - Find related context
-- `trie_query_context` - Natural language queries across all signals
-
-**Why query tools matter**: Instead of dumping everything into context, agents ask for exactly what they need. This prevents context pollution and keeps agents focused.
-
-## Advanced Features
-
-<details>
-<summary><b>Goals & Custom Rules</b></summary>
-
-Set improvement goals that are actively enforced in real-time:
+### Proactive Warnings
 
 ```bash
-# Add goals
-trie goal add "No hardcoded API keys"
-trie goal add "All async functions must handle errors"
-trie goal add "Every TODO must have a ticket reference"
-
-# View progress
-trie goal list
-
-# Get unresolved violations
-trie_get_nudges  # Via MCP
-```
-
-Goals use AI-powered semantic understanding to catch violations, not just keyword matching.
-
-</details>
-
-<details>
-<summary><b>Fix Triage System</b></summary>
-
-Trie routes each issue to one of three fix strategies:
-
-| Strategy | When | Action |
-|----------|------|--------|
-| **inline-auto** | Trivial fixes (score < 0) | Apply automatically |
-| **local-ai** | Moderate risk (score 0–3) | `trie_fix` — local AI applies fix |
-| **cloud-agent** | High risk (score ≥ 4) | `trie_cloud_fix` — Cursor cloud agent |
-
-See routing plan before applying:
-```bash
-trie_fix action:route
-```
-
-</details>
-
-<details>
-<summary><b>Team Sync (Shared Ledger)</b></summary>
-
-Sync ledger blocks across your team:
-
-```bash
-trie sync init              # Initialize shared storage
-trie sync pull              # Pull shared updates
-trie sync push              # Push local changes
-trie sync status            # Show sync state
-trie sync hooks --install   # Install auto-sync git hooks
-```
-
-The shared ledger lives in `.trie-shared/` with hot/cold storage tiers and automatic compression.
-
-</details>
-
-<details>
-<summary><b>Memory Management</b></summary>
-
-```bash
-# Search incident history
-trie memory search "authentication"
-trie memory stats
-trie memory recent
-
-# Clean up old issues (doesn't affect immutable ledger)
-trie memory purge smart      # Remove resolved & old low-priority
-trie memory purge resolved   # All resolved issues
-trie memory purge old        # Older than 90 days
-```
-
-</details>
-
-<details>
-<summary><b>Git Hooks</b></summary>
-
-Installed automatically with `trie init`:
-
-- **pre-commit** - Scan staged files, block on critical issues
-- **post-commit** - Update context graph
-- **pre-push** - Block push on critical issues
-
-**Bypass methods:**
-```bash
-git push --no-verify         # Skip all hooks
-TRIE_BYPASS=1 git push      # Skip Trie but log bypass
-```
-
-</details>
-
-## How It Works
-
-### Memory Architecture
-
-Trie maintains two complementary memory systems:
-
-**1. Governance Ledger** (`.trie/memory/ledger.json`)
-- Append-only chain with Ed25519 signatures
-- Tamper-evident, never deleted (only corrected)
-- Used for: audit trail, compliance, gotcha predictions
-- Auto-commits to Git for distributed backup
-
-**2. Issue Memory** (`.trie/memory/issues.json`)
-- Fast searchable cache of detected issues
-- Can be compacted and purged
-- Used for: pattern recognition, quick queries
-- Links back to ledger via `ledgerBlockHash`
-
-Both systems sync across your team and travel with your codebase via Git.
-
-### Trie-Based Autocomplete
-
-Trie uses prefix trees (tries) for fast O(m) autocomplete on ledger data:
-
-**Ledger Trie** (`src/trie/ledger-trie.ts`)
-- Indexes governance tags for discovery (e.g., "auth" → "auth", "authentication", "authorization")
-- Indexes file paths from governance for quick lookups
-- Indexes agent names for history queries
-- Integrated into tiered storage for instant autocomplete
-
-**Usage in MCP:**
-- Agents can autocomplete tags when querying governance
-- Fast prefix search on file paths and agent names
-- Makes the ledger more discoverable and navigable
-
-### File Structure
-
-```
-your-project/
-├── .trie/
-│   ├── memory/
-│   │   ├── ledger.json     # Governance ledger (cryptographic chain)
-│   │   └── issues.json     # Issue cache
-│   ├── warm/
-│   │   └── decisions.db    # SQLite database for structured queries
-│   ├── context.json        # Project knowledge graph
-│   ├── config.json         # Settings
-│   └── keys/               # Ed25519 signing keys (never committed)
-├── .trie-shared/           # Shared ledger for team sync (optional)
-│   ├── active/
-│   ├── archived/
-│   └── ledger-manifest.json
-└── .git/
-```
-
-### Signal Extraction & AI Analysis
-
-Trie uses AI throughout for intelligent analysis:
-
-**Signal Extraction** (`signal-extractor.ts`)
-Instead of dumping raw logs into context, Trie extracts structured signals:
-
-**Input:** Incident report, commit, conversation  
-**Extraction:** AI (Claude Haiku/Sonnet) pulls out structured data:
-- **Governance**: "Chose bcrypt over sha256 for password hashing"
-- **Facts**: "Stripe requires TLS 1.2+ for EU transactions"
-- **Blockers**: "Missing VAT validation blocks EU checkout"
-- **Questions**: "Should we cache session tokens?"
-
-**Storage:** Goes to queryable database with trie-based indexing  
-**Query:** Agents ask for targeted context via autocomplete, not everything at once
-
-**AI-Powered Learning** (`learning-engine.ts`)
-- Analyzes git `fix` and `revert` commits to understand root causes
-- Extracts patterns and categories (logic-error, null-check, race-condition)
-- Stores lessons in the ledger for future predictions
-- Falls back gracefully if AI unavailable
-
-**AI-Powered Gotcha** (`gotcha-predictor.ts`)
-- Analyzes code semantically for bugs and security issues
-- Considers governance context and active blockers
-- Returns structured predictions with risk levels
-- Uses Claude Sonnet 4 for deep code understanding
-
-This prevents context pollution and keeps agents focused on relevant signals.
-
-## CLI Reference
-
-### Basic Commands
-
-```bash
-trie init          # Set up Trie in your project
-trie status        # View project health and memory stats
-trie tell          # Report incidents (extracts decisions, facts, blockers)
-trie gotcha        # Predict problems with current changes
-trie learn         # Train from git history or feedback
-trie watch         # Start interactive monitoring dashboard
+trie init
 ```
 
-### Goals
+This adds Cursor rules and CLAUDE.md guidance so agents call `trie_check_file` before editing files and read `trie://context` at conversation start.
 
-```bash
-trie goal add "<goal>"     # Set improvement goal
-trie goal list             # View progress
-```
+## CLI Commands
 
-### Memory
+| Command | Description |
+|---------|-------------|
+| `trie init` | Add Cursor/Claude rules for proactive file checks |
+| `trie login` | Sign in via browser (OAuth) |
+| `trie logout` | Revoke session |
+| `trie teams [list\|switch <teamId>]` | List or switch teams |
+| `trie pull [context\|graph\|signals\|documents\|ledger\|all]` | Fetch cloud data (JSON) |
+| `trie status` | Show auth and cache status |
 
-```bash
-trie memory search "query"  # Search incident history
-trie memory stats           # View statistics
-trie memory recent          # Recent issues
-trie memory purge smart     # Clean up old/resolved
-```
+## MCP Tools
 
-### Ledger
+| Tool | Description |
+|------|-------------|
+| `trie_context` | Consolidated context: hot zones, graph summary, recent signals/documents |
+| `trie_check_file` | Risk assessment for a file (incidents, alerts, decisions) |
+| `trie_graph` | Read ANT graph from cloud |
+| `trie_signals` | Read signals feed |
+| `trie_documents` | Read cloud documents |
+| `trie_ledger` | Read cloud ledger entries |
+| `trie_search` | Natural language search over cloud context |
 
-```bash
-trie ledger verify          # Validate chain integrity
-trie ledger history         # Show blocks with authors
-trie ledger stats           # Block counts, entries, severity
-trie ledger correct <id>    # Mark entry as corrected
-trie ledger corrections     # View correction stats
-```
-
-### Sync
-
-```bash
-trie sync init              # Initialize shared ledger
-trie sync pull              # Pull from shared storage
-trie sync push              # Push to shared storage
-trie sync status            # Show sync state
-trie sync hooks --install   # Install auto-sync git hooks
-```
+## MCP Resources
 
-### Keys
+| URI | Description |
+|-----|-------------|
+| `trie://context` | Consolidated context with hot zones and active signals |
+| `trie://graph` | Raw ANT graph from cloud |
 
-```bash
-trie keys generate          # Generate Ed25519 signing key
-trie keys status            # Check if signing is configured
-trie keys public            # Get your public key
-```
+**Usage:** Agents should read `trie://context` at conversation start and call `trie_check_file` before editing high-risk files.
 
-### Feedback
+## Configuration
 
-```bash
-trie ok          # Pattern is good
-trie bad         # Pattern is bad
-trie pause       # Disable warnings for 1 hour
-```
+Auth and config are stored locally (keychain-backed where available). The API base URL defaults to `https://trie-api.vercel.app` and can be overridden with `TRIE_API_BASE_URL`.
 
-### Setup
+## Development
 
 ```bash
-trie setup                     # Show setup guide
-trie setup slack <webhook>     # Configure Slack
-trie setup test-slack          # Test Slack connection
-trie linear auth <key>         # Configure Linear
-trie linear sync               # Sync Linear tickets
+npm install
+npm run build
+npm test
 ```
 
-## Configuration
-
-Create `.trie/config.json`:
-
-```json
-{
-  "scanOptions": {
-    "maxConcurrency": 4,
-    "timeoutMs": 30000
-  },
-  "integrations": {
-    "slack": {
-      "enabled": true,
-      "webhook": "https://hooks.slack.com/...",
-      "channel": "#security"
-    }
-  },
-  "autoEscalation": {
-    "enabled": true,
-    "quietHours": { "start": "21:00", "end": "08:00" }
-  }
-}
-```
-
-## Troubleshooting
-
-**Trie not finding issues**: You haven't taught Trie about your patterns yet. Use `trie tell` to report incidents.
-
-**Memory queries returning empty**: Report incidents with `trie tell` or run `trie learn` to extract from git history.
-
-**Query tools not working**: Make sure you've initialized with `trie init` and have `ANTHROPIC_API_KEY` set.
-
-**Hooks not working**: Reinstall with `trie init`. Check write permissions to `.git/hooks/`.
-
-**Goals showing but not detecting violations**: Goals may not be active in project state. Run `trie goal add "<goal>"` to activate.
-
-**Quick start:**
-1. Fork and clone the repository
-2. `npm install`
-3. Copy `.env.example` to `.env.local` and add API keys
-4. `npm run build`
-5. `npm test`
-
 **Before submitting:**
-- All tests pass (`npm test`)
-- Type checking passes (`npm run typecheck`)
-- Follow code style (`npm run lint`)
-- Update docs for new features
-- Never commit secrets or API keys
-
+- Tests pass (`npm test`)
+- Typecheck passes (`npm run typecheck`)
+- Lint passes (`npm run lint`)
 
 ## License