@triedotdev/mcp 1.0.83 → 1.0.84

package/README.md

@@ -1,5 +1,627 @@
 # Trie: Trainable AI Agent for Maintaining AI-Generated Codebases
 
+A trainable AI agent that watches all of your codebases, learns from your incidents, and prevents repeat bugs before they ship.
+
+Download Workspace Follow on X
+
+## What Trie Does
+
+Central skill repository: One place for all your skills — carry context and rules across Cursor, Claude, VS Code, CLI, and CI/CD. Unlike running skills with Claude Code, Trie will check for anything malicious before you run them.  
+Sets and tracks goals: "Reduce login bugs by 50%" then actually measures progress and celebrates wins  
+Tests your theories: "Mondays have more bugs" — Trie validates with real data and builds confidence over time  
+Learns from your incidents: Train it on your specific patterns, not generic rules that don't fit your prompting  
+Predicts "Gotchas" proactively: Ingests Linear tickets and correlates them with past failures to warn you before you even push code
+
+## Goal
+
+Trie exists so you can maintain multiple codebases as one person without losing your mind.
+
+Every bug you fix teaches Trie a pattern that protects all your projects. Every incident you report becomes institutional knowledge that travels with your code. Every decision you make—and the tradeoffs you considered—gets remembered across Cursor, Claude, VS Code, CLI, and CI/CD.
+
+Instead of burning tokens on the same questions across different repos or forgetting why you architected something a certain way six months ago, Trie remembers for you. Instead of losing track of edge cases and tradeoffs as you switch between tools, Trie maintains system coherence. The result is faster development with fewer production fires, because your personal AI agent gets smarter every time something breaks instead of starting from zero in every conversation.
+
+Your thinking and planning keep up with code generation. Your decisions persist across tools. Your edge cases don't get forgotten.
+
+## Quick Start
+
+### 1. Install Trie
+
+Make sure you have Node.js installed, then:
+
+```bash
+# Install Trie globally
+npm install -g trie
+
+# Set up in your project
+cd your-project
+trie init
+```
+
+### 2. Run Your First Scan
+
+```bash
+# Scan your entire codebase
+trie scan
+
+# Quick health check
+trie status
+```
+
+### 3. Start Teaching Trie
+
+When bugs happen, tell Trie about them:
+
+```bash
+# Report a specific incident
+trie tell "Users can't log in after password reset"
+
+# Train Trie from your history (reverts/bugfixes)
+trie learn
+
+# Give feedback on patterns (staged files)
+trie ok    # Pattern is good
+trie bad   # Pattern is bad
+```
+
+## Why Trie Exists
+
+Building apps with AI tools like Cursor and Claude Code is incredibly fast - but maintaining them alone is a nightmare. You fix a bug and forget why it happened. The same issues keep coming back. Your codebase grows faster than your memory of it.
+
+The real challenge isn't generating code—it's maintaining it. Real software has countless edge cases. Every architectural decision involves tradeoffs. As you switch between Cursor, Claude Code, terminal, and CI/CD, context gets lost. You make a decision in one tool, forget it in another, and repeat the same mistakes.
+
+You shipped an MVP. You've got traction. Maybe even paying customers. Now you're in the maintenance phase—where the hard work happens. Where you handle edge cases, make tradeoffs, and keep the system coherent as it grows. Where you need your thinking and planning to keep pace with rapid code generation.
+
+Trie remembers your decisions across tools, tracks the tradeoffs you've made, and maintains system coherence as your codebase evolves. It solves this by being your persistent memory. It keeps a ledger so it remembers what broke before, learns patterns across your projects, and warns you before you ship risky code. Tools like Cursor Bugbot are great, but just flagging issues isn't going to help you avoid similar patterns in the future. With Trie, you'll find quickly that you end up architecting apps and prompting better.
+
+## Key Features
+
+### Smart Memory
+
+Git-based storage - Your project's memory travels with your code in .trie/ folder  
+Cross-project learning - Patterns discovered in one project help prevent bugs in others  
+Incident tracking - Build a searchable history of what went wrong and why  
+Decision memory - Remembers architectural choices and tradeoffs across Cursor, Claude, VS Code, CLI, and CI/CD  
+Context that travels - Your thinking and planning keep up with code generation across all your tools
+
+### Intelligent Analysis
+
+26 built-in scouts - Automated analyzers for security, performance, accessibility, and more  
+Custom skills - Add external analyzers from the community  
+Risk scoring - Intelligent priority ranking based on your actual incident history  
+Edge case detection - Identifies recurring issues and patterns you've hit before  
+System coherence - Tracks relationships between files, changes, incidents, fixes, and decisions
+
+### Development Integration
+
+Git hooks - Automatic checks before commits and pushes  
+Watch mode - Real-time monitoring while you code  
+Fast performance - Sub-500ms checks, won't slow down your workflow
+
+### Developer Experience
+
+Plain English warnings - "This auth change broke twice before" instead of cryptic codes  
+Multiple interfaces - CLI, MCP tools for Claude/Cursor, visual dashboards  
+Flexible workflow - Works with any editor, any git workflow, any deployment setup
+
+## How It Works
+
+### The Guardian System
+
+Trie uses a "Guardian Agent" architecture:
+
+Scouts continuously analyze your code for potential issues  
+Guardian receives scout reports and decides what matters based on your history  
+Memory Tree stores incident patterns using a trie data structure for fast lookups  
+Learning Loop improves predictions based on your feedback
+
+### Memory That Travels
+
+```
+your-project/
+├── .trie/
+│   ├── memory/          # Incident history
+│   ├── patterns/        # Learned patterns
+│   ├── context.json     # Project knowledge graph
+│   ├── context.db       # SQLite graph (decisions, relationships)
+│   └── config.json      # Settings
+├── src/
+└── .git/
+```
+
+The .trie/ folder commits with your code, so your project's intelligence is preserved and shared across:
+
+Local development  
+CI/CD pipelines  
+Team members  
+Different machines
+
+### Decision Memory Across Tools
+
+Trie maintains a Context Graph that tracks decisions, tradeoffs, and architectural choices:
+
+Decision nodes store why you made certain choices and what tradeoffs were considered  
+Cross-tool access - Cursor, Claude, VS Code, CLI, and CI/CD all read from the same .trie/ folder  
+Context trail - Knows which environment ran which analysis and when  
+Relationship tracking - Files ↔ Changes ↔ Incidents ↔ Fixes ↔ Decisions
+
+When you switch from Cursor to Claude Code to terminal, Trie remembers. Your thinking and planning keep up with code generation because every tool shares the same memory.
+
+## Core Workflow
+
+### 1. Teaching Phase
+
+```bash
+# Something breaks in production
+trie tell "Payment processing failed for EU customers"
+
+# Trie learns: "payments/" + "EU" + "failed" = high risk pattern
+# Also records: decision context, affected files, tradeoffs made
+```
+
+### 2. Prevention Phase
+
+```bash
+# Later, you modify payment code
+git add src/payments/eu-handler.js
+git commit -m "Update EU payment logic"
+
+# Trie warns: "This area broke 2 weeks ago with EU payments. Consider extra testing."
+# Context: Remembers the decision you made last time, the edge case that caused the issue
+```
+
+### 3. Feedback Loop
+
+```bash
+# Warning was helpful
+trie ok
+
+# Warning was wrong
+trie bad
+
+# Trie adjusts confidence for similar future warnings
+# Also updates: decision patterns, edge case recognition, tradeoff understanding
+```
+
+### 4. Maintenance Phase
+
+This is where Trie shines. As your app grows and you handle edge cases:
+
+```bash
+# Working in Cursor, you make a decision about error handling
+# Trie records it in the context graph
+
+# Switch to Claude Code later
+# Same context graph, same decisions remembered
+
+# Push from terminal
+# Git hooks check against your full history of decisions and incidents
+
+# CI/CD runs
+# Same checks, same memory, same coherence
+```
+
+Edge cases, tradeoffs, and system coherence—Trie handles the hard part that can't be automated by remembering what you decided, why you decided it, and what happened as a result.
+
+## Advanced Features
+
+### Goals & Hypotheses
+
+Set improvement goals and test theories:
+
+```bash
+# Set a goal
+trie goal add "Reduce authentication bugs by 50%"
+
+# Add a hypothesis
+trie hypothesis add "Code reviews reduce bug rate"
+
+# Trie tracks progress and validates hypotheses over time
+```
+
+### Watch Mode
+
+Real-time monitoring with visual dashboard:
+
+```bash
+trie watch
+```
+
+Interactive panels for goals, memory, scout activity, and more.
+
+Running in Background: To keep trie watch running in the background, use screen or tmux:
+
+```bash
+# Using screen
+screen -S trie-watch
+trie watch
+# Press Ctrl+A then D to detach
+# Reattach with: screen -r trie-watch
+
+# Using tmux
+tmux new -s trie-watch
+trie watch
+# Press Ctrl+B then D to detach
+# Reattach with: tmux attach -t trie-watch
+```
+
+This allows you to keep the guardian running while using other terminals. The interactive dashboard will be available when you reattach.
+
+### JIT Defect Prediction ("Gotchas")
+
+Trie connects to your issue tracker and project history to predict problems while you work:
+
+```bash
+# 1. Connect Linear
+trie linear auth <your-api-key>
+trie linear sync
+
+# 2. Learn from history automatically
+trie learn
+
+# 3. Predict for current changes
+trie gotcha
+```
+
+Trie will warn you if your current task correlates with historical regressions or high-risk signatures.
+
+### Integration with AI Coding Tools
+
+Trie provides MCP (Model Context Protocol) tools for seamless integration with Claude, Cursor, and other AI assistants:
+
+trie_scan - Analyze code with AI-friendly output  
+trie_check - Quick risk assessment  
+trie_tell - Report incidents  
+trie_memory - Search incident history  
+trie_fix - Apply suggested fixes
+
+## Built-in Scouts
+
+Trie includes 26 specialized analyzers:
+
+### Security & Compliance
+
+Security Scout - Vulnerabilities, injection risks, secrets  
+Privacy Scout - PII handling, GDPR/HIPAA compliance  
+Legal Scout - Regulatory compliance patterns  
+SOC2 Scout - Access controls, audit trails
+
+### Code Quality
+
+Bug Scout - Common bugs, edge cases, null safety  
+Architecture Scout - SOLID principles, scalability issues  
+Types Scout - Type errors, missing annotations  
+Clean Scout - AI-generated code cleanup
+
+### User Experience
+
+Accessibility Scout - WCAG compliance, screen readers  
+UX Scout - User journey analysis, usability issues  
+Design Scout - Visual consistency, design systems
+
+### Operations
+
+DevOps Scout - Configuration issues, deployment patterns  
+Performance Scout - Speed bottlenecks, optimization opportunities
+
+View all scouts →
+
+## Installation & Setup
+
+### Requirements
+
+Node.js 16 or higher  
+Git repository
+
+### Installation
+
+```bash
+# Install globally
+npm install -g trie
+
+# Or use npx for one-time runs
+npx trie scan
+```
+
+### Project Setup
+
+```bash
+# Initialize in your project
+cd your-project
+trie init
+
+# This creates:
+# - .trie/ directory with initial config
+# - Git hooks for automatic checking
+# - Bootstrap files (optional)
+```
+
+### API Key Configuration
+
+Trie works best with these keys:
+
+ANTHROPIC_API_KEY: Enables AI-powered analysis and explanations.  
+LINEAR_API_KEY: Enables JIT defect prediction by syncing your active tickets.
+
+#### 1. Set via Environment (Recommended for MCP)
+
+Add these to your .env file or shell config:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+export LINEAR_API_KEY=lin_api_...
+```
+
+#### 2. Set via CLI (Persistent per project)
+
+```bash
+trie linear auth <your-key>
+```
+
+#### 3. Set in MCP Config (Cursor/Claude Code)
+
+Add to your MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "trie": {
+      "command": "npx",
+      "args": ["-y", "@triedotdev/mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "your-key",
+        "LINEAR_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### AI Tool Integration
+
+For Claude (MCP): Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "trie": {
+      "command": "trie",
+      "args": ["mcp"],
+      "env": {
+        "ANTHROPIC_API_KEY": "your-api-key-here",
+        "LINEAR_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+For Cursor: Cursor has built-in MCP support. Add the above configuration to your Cursor MCP settings.
+
+Note: VS Code extension is coming soon.
+
+## CLI Reference
+
+### Basic Commands
+
+```bash
+trie init          # Set up Trie in your project
+trie scan          # Analyze codebase with intelligent skill selection
+trie status        # View project health and memory stats
+trie learn         # Train Trie from history or feedback
+trie gotcha        # Predict problems with current changes
+```
+
+### Memory Management
+
+```bash
+trie memory search "auth"     # Search incident history
+trie memory stats             # View memory statistics
+trie memory purge smart       # Clean up old/resolved issues
+trie learn                    # Extract patterns from reverts/fixes
+```
+
+### Goals & Learning
+
+```bash
+trie goal add "<goal>"           # Set improvement goal
+trie hypothesis add "<theory>"   # Test a hypothesis
+trie goal list                   # View progress
+trie linear sync                 # Sync Linear tickets for intent context
+```
+
+### Feedback & Training
+
+```bash
+trie ok          # Pattern is good (alias: learn ok)
+trie bad         # Pattern is bad (alias: learn bad)
+trie learn       # Learn from your git history
+trie pause       # Disable warnings for 1 hour
+```
+
+### Watch Mode
+
+```bash
+trie watch       # Start interactive monitoring dashboard
+
+# Run in background with screen/tmux:
+screen -S trie-watch && trie watch    # Detach: Ctrl+A, D
+tmux new -s trie-watch && trie watch  # Detach: Ctrl+B, D
+```
+
+## Configuration
+
+### Scan Behavior
+
+Create .trie/config.json:
+
+```json
+{
+  "scanOptions": {
+    "maxConcurrency": 4,
+    "timeoutMs": 30000,
+    "includeNodeModules": false
+  },
+  "autoEscalation": {
+    "enabled": true,
+    "webhookUrl": "https://hooks.slack.com/...",
+    "quietHours": { "start": "21:00", "end": "08:00" }
+  }
+}
+```
+
+### Git Hooks
+
+Installed automatically with trie init:
+
+pre-commit - Quick scan of staged files  
+post-commit - Update context graph  
+pre-push - Block critical issues (can be bypassed)
+
+To bypass:
+
+```bash
+git push --no-verify              # Skip all hooks
+TRIE_BYPASS=1 git push           # Skip Trie but log bypass
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```bash
+# Generate workflow file
+trie ci github
+
+# Creates .github/workflows/trie.yml with:
+# - Full codebase scan
+# - Memory caching for speed
+# - SARIF upload for GitHub Security tab
+```
+
+### Custom CI
+
+```bash
+# In your CI pipeline
+npm install -g trie
+trie scan --output=sarif > trie-results.sarif
+```
+
+## Memory System
+
+### Local Memory
+
+Each project stores its own memory in .trie/memory/:
+
+Incident reports and patterns  
+Risk scores and confidence levels  
+Performance over time
+
+### Cross-Project Memory
+
+Global patterns stored in ~/.trie/memory/:
+
+Patterns that apply across projects  
+Skill effectiveness data  
+Your personal coding patterns
+
+### Memory Management
+
+```bash
+# View capacity (default: 10,000 issues)
+trie memory stats
+
+# Smart cleanup (removes resolved + old low-priority)
+trie memory purge smart
+
+# Remove all resolved issues
+trie memory purge resolved
+
+# Remove issues older than 90 days
+trie memory purge old --days=90
+```
+
+What happens at the 10,000 issue cap: Trie will deduplicate new repeats, compact older issues into summaries, and if it still exceeds the cap it will prune the oldest/lowest-value issues (it does not “overwrite” in place).
+
+## Custom Skills
+
+### Adding External Skills
+
+```bash
+# From skill repositories
+trie skill install vercel/ai-best-practices
+trie skill install anthropic/typescript-patterns
+
+# From any GitHub repo
+trie skill install username/repo-name
+```
+
+### Security & Safe Installation
+
+Trie automatically scans all skills for security risks before installation.
+
+When installing skills:
+
+Skills are scanned for malicious patterns  
+Critical risks flagged with strong warnings  
+High risks flagged with warnings  
+Shell commands Trie runs are logged to .trie/audit/ (e.g. skill install git clone, PR review git/gh, skill gating which/where, file picker helpers)
+
+```bash
+# View audit logs
+trie audit logs
+
+# View security info for installed skill
+trie skills info skill-name
+```
+
+Best Practices:
+
+Only install from trusted sources (verified organizations)  
+Review security warnings and all .md carefully before using  
+Check audit logs periodically: trie audit stats (and investigate anything unexpected with trie audit skill <name>)
+
+### Creating Your Own Skills
+
+```bash
+# Create from documentation
+trie skill create my-skill --doc=./coding-standards.md
+
+# This creates a custom analyzer based on your documentation
+```
+
+### Skill Format
+
+Skills are simple markdown files with detection rules:
+
+```markdown
+# My Custom Skill
+
+## Detection Rules
+- File patterns: `*.js`, `*.ts`
+- Code patterns: `console.log`, `debugger`
+
+## Analysis
+Look for debugging statements left in production code.
+
+## Fix Suggestions
+Remove or replace with proper logging.
+```
+
+## Troubleshooting
+
+### Common Issues
+
+Trie not finding issues: Your codebase might be very clean, or you haven't taught Trie about your specific patterns yet. Try trie tell to report some known issues.
+
+Scans are slow: Reduce concurrency with --max-concurrency=2 or exclude large directories in config.
+
+Too many false positives: Use trie bad to train Trie, and consider adjusting scout sensitivity in config.
+
+Hooks not working: Reinstall with trie init. Make sure you have write permissions to .git/hooks/.
+
+this is what our github readme should say
+# Trie: Trainable AI Agent for Maintaining AI-Generated Codebases
+
 **A trainable AI agent that watches all of your codebases, learns from your incidents, and prevents repeat bugs before they ship.**
 
 [![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)

package/dist/{chunk-W4SQE6F7.js → chunk-4U3DNRUA.js}

@@ -3,15 +3,15 @@ import {
   getSkillRegistry,
   loadContextState,
   runExecFile
-} from "./chunk-CGALCUZE.js";
+} from "./chunk-Z6JP2QQU.js";
 import {
   getGlobalMemoryStats
-} from "./chunk-EWIEXQES.js";
+} from "./chunk-KGVKUMFO.js";
 import {
   getHistoricalInsights,
   getMemoryStats,
   getRecentIssues
-} from "./chunk-WGECLUDQ.js";
+} from "./chunk-7UPNCM66.js";
 import {
   getWorkingDirectory
 } from "./chunk-CM7EHNQK.js";
@@ -2245,4 +2245,4 @@ export {
   getSkillsByCategory,
   getSkillCategories
 };
-//# sourceMappingURL=chunk-W4SQE6F7.js.map
+//# sourceMappingURL=chunk-4U3DNRUA.js.map

package/dist/{chunk-YHQYOD6M.js → chunk-4UVTFL2T.js}

@@ -8,10 +8,10 @@ import {
   getUncommittedChanges,
   getWorkingTreeDiff,
   loadConfig
-} from "./chunk-W4SQE6F7.js";
+} from "./chunk-4U3DNRUA.js";
 import {
   ContextGraph
-} from "./chunk-B7CLAOEK.js";
+} from "./chunk-THJKXIMJ.js";
 import {
   scanForVulnerabilities
 } from "./chunk-FCMAQSV7.js";
@@ -23,7 +23,7 @@ import {
 } from "./chunk-6NLHFIYA.js";
 import {
   storeIssues
-} from "./chunk-WGECLUDQ.js";
+} from "./chunk-7UPNCM66.js";
 import {
   getWorkingDirectory
 } from "./chunk-CM7EHNQK.js";
@@ -1459,8 +1459,9 @@ var LearningEngine = class {
    * Record manual feedback (trie ok/bad) and adjust pattern confidence
    */
   async recordManualFeedback(helpful, files, note) {
+    const context = files[0] ?? "unspecified";
     const decision = await this.graph.addNode("decision", {
-      context: files.length > 0 ? files[0] : "unspecified",
+      context,
       decision: helpful ? "helpful" : "not helpful",
       reasoning: note ?? null,
       outcome: helpful ? "good" : "bad",
@@ -1543,10 +1544,8 @@ var LearningEngine = class {
 
 // src/ingest/linear-ingester.ts
 var LinearIngester = class {
-  projectPath;
   graph;
-  constructor(projectPath, graph) {
-    this.projectPath = projectPath;
+  constructor(_projectPath, graph) {
     this.graph = graph;
   }
   async syncTickets() {
@@ -1688,4 +1687,4 @@ export {
   LearningEngine,
   LinearIngester
 };
-//# sourceMappingURL=chunk-YHQYOD6M.js.map
+//# sourceMappingURL=chunk-4UVTFL2T.js.map