@triedotdev/mcp 1.0.93 → 1.0.97

package/README.md

@@ -1,26 +1,41 @@
-# Trie: Trainable AI Agent for Maintaining AI-Generated Codebases
+# Trie: Trainable AI Agent for AI-Generated Codebases
 
-**A trainable AI agent that watches all of your codebases, learns from your incidents, and prevents repeat bugs before they ship.**
+**Your autonomous agent that learns from every incident, extracts decisions from every change, and predicts problems before they happen.**
 
 [![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)
 
 ## 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
+Trie is an **autonomous, trainable AI agent** that maintains a decision ledger for your codebase:
+
+- **🤖 Autonomous Operation**: Run `trie watch` and the agent monitors your codebase 24/7
+- **🧠 Intelligent Extraction**: Automatically extracts decisions, facts, blockers from every change
+- **📊 Decision Ledger**: Builds institutional knowledge that travels from Cursor → CLI → CI/CD
+- **🎯 Predictive Intelligence**: `trie gotcha` queries the ledger to predict problems before they happen
+- **📈 Continuous Learning**: Feed it incidents with `trie tell`, teach it patterns with your history
+
+The agent learns from every incident, decision, and fix. When you ship, Trie remembers. When something breaks, Trie learns. Over time, your agent gets better at predicting what will go wrong before it does.
 
 ## Goal
 
-Trie exists so you can maintain multiple codebases as one person without losing your mind. 
+**Trie is your personal AI agent that maintains multiple codebases without losing context.**
+
+Every bug you fix teaches the agent 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 extracted and stored automatically by the agent.
+
+Instead of burning tokens on the same questions across different repos or forgetting why you architected something a certain way six months ago, **your agent remembers for you**. Instead of losing track of edge cases and tradeoffs as you switch between tools, **your agent maintains system coherence**.
+
+The result is faster development with fewer production fires, because **your agent gets smarter every time something breaks** instead of starting from zero in every conversation.
 
-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.
+### How the Agent Works
 
-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.
+1. **`trie watch`** - Start the agent, it monitors your codebase autonomously
+2. **Agent Extracts** - Every file change → extract decisions, facts, blockers
+3. **Agent Stores** - Builds decision ledger with rich metadata and tag expansion
+4. **`trie gotcha`** - Agent queries ledger to predict problems in your current changes
+5. **`trie tell`** - Feed agent incidents to improve its predictions
+6. **Agent Learns** - Gets better at predicting what matters in YOUR codebase
 
-**Your thinking and planning keep up with code generation. Your decisions persist across tools. Your edge cases don't get forgotten.**
+**Your thinking and planning keep up with code generation. Your decisions persist across tools. Your edge cases don't get forgotten. Your agent handles it all.**
 
 ## Quick Start
 
@@ -37,30 +52,49 @@ cd your-project
 trie init
 ```
 
-### 2. Run Your First Scan
+### 2. Start the Agent
+
+The agent runs autonomously, watching your codebase and building the decision ledger:
 
 ```bash
-# Scan your entire codebase
-trie scan
+# Start the autonomous agent
+trie watch
 
-# Quick health check
-trie status
+# The agent now:
+# - Watches file changes in real-time
+# - Extracts decisions, facts, blockers from every change
+# - Builds decision ledger automatically
+# - Predicts problems based on historical patterns
 ```
 
-### 3. Start Teaching Trie
+### 3. Teach the Agent
 
-When bugs happen, tell Trie about them:
+When bugs happen, teach the agent:
 
 ```bash
-# Report a specific incident
-trie tell "Users can't log in after password reset"
+# Report a specific incident (agent extracts structured signals)
+trie tell "Users can't log in after password reset - bcrypt config was wrong"
 
-# Train Trie from your history (reverts/bugfixes)
+# Train agent from your git history (reverts/bugfixes)
 trie learn
 
-# Give feedback on patterns (staged files)
-trie ok    # Pattern is good
-trie bad   # Pattern is bad
+# Query what the agent knows
+trie gotcha  # Predicts problems in your current changes
+```
+
+### 4. Let the Agent Work
+
+The agent learns continuously:
+- Every commit → Extracts decisions
+- Every incident → Learns patterns  
+- Every fix → Updates predictions
+- Every change → Queries ledger for "gotchas"
+
+**Set `ANTHROPIC_API_KEY` for full signal extraction** (Claude Haiku for fast, cheap extraction)
+
+# Give feedback on predictions
+trie ok    # Prediction was helpful
+trie bad   # Prediction was wrong
 ```
 
 ## Why Trie Exists
@@ -85,8 +119,6 @@ Trie remembers your decisions across tools, tracks the tradeoffs you've made, an
 
 ### 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.
@@ -109,8 +141,8 @@ Trie remembers your decisions across tools, tracks the tradeoffs you've made, an
 
 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.
+- Analyzes your code for potential issues based on your incident history.
+- Guardian 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.
 
@@ -119,10 +151,13 @@ Trie uses a "Guardian Agent" architecture:
 ```
 your-project/
 ├── .trie/
+│   ├── hot/             # In-memory current session
+│   ├── warm/            # Queryable decisions DB
+│   │   └── decisions.db # SQLite database
+│   ├── cold/            # Archived history
 │   ├── memory/          # Incident history
 │   ├── patterns/        # Learned patterns
 │   ├── context.json     # Project knowledge graph
-│   ├── context.db       # SQLite graph (decisions, relationships)
 │   └── config.json      # Settings
 ├── src/
 └── .git/
@@ -146,6 +181,61 @@ 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.
 
+### Signal Extraction: Context Without Pollution
+
+**The Problem**: Agents drown in raw data. Dumping 10,000 lines of logs, 500 Slack messages, and 200 commits into context is expensive and ineffective.
+
+**Trie's Solution**: Extract signal, not noise.
+
+#### Three-Tier Architecture
+
+```
+HOT (In-Memory)
+└─ Current session data
+   └─ Active decisions being worked on
+   
+WARM (Queryable DB)
+└─ Recent decisions, facts, blockers
+   └─ Agents query what they need: "decisions related to auth in last 30 days"
+   └─ Fast retrieval, targeted results
+   
+COLD (Archived)
+└─ Full history, indexed but dormant
+   └─ Moves here after 90 days of low access
+```
+
+#### How Extraction Works
+
+1. **Raw Input** → You report an incident or commit code
+2. **Extraction** → Cheap model (Haiku) pulls out structured signals:
+   - **Decisions**: "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?"
+
+3. **Storage** → Structured data goes to WARM storage with embeddings
+4. **Query** → Agents ask: `trie_get_decisions(relatedTo: "payments")`
+5. **Targeted Context** → Agent gets 5 relevant decisions, not 5,000 raw logs
+
+#### MCP Query Tools
+
+Agents don't get dumps—they **query** for what they need:
+
+```typescript
+// Agent queries decision ledger
+trie_get_decisions({
+  relatedTo: "auth/validator.ts",
+  since: "30d",
+  limit: 5
+})
+
+// Returns targeted context:
+// 1. "Always validate email before Stripe checkout" (3 weeks ago)
+// 2. "EU customers need VAT validation" (2 months ago)
+```
+
+**Why this matters**: Context management IS the product. Agents get the right information at the right moment, not everything dumped at once.
+
 ## Core Workflow
 
 ### 0. Planning Phase
@@ -242,7 +332,7 @@ Real-time monitoring with visual dashboard:
 trie watch
 ```
 
-Interactive panels for goals, memory, scout activity, and more.
+Interactive panels for goals, memory, analysis activity, and more.
 
 Running in Background: To keep trie watch running in the background, use screen or tmux:
 
@@ -284,40 +374,19 @@ Trie will warn you if your current task correlates with historical regressions o
 
 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  
+**Core Tools:**  
+trie_tell - Report incidents and extract structured signals  
 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
+**Query Tools (NEW - Signal Extraction):**  
+trie_get_decisions - Query decisions with filters (tags, time, file)  
+trie_get_blockers - Get active blockers only  
+trie_get_related_decisions - Find related context  
+trie_query_context - Natural language queries across all signal types
 
-### 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
+**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 on relevant signal.
 
 ## Installation & Setup
 
@@ -419,7 +488,7 @@ Note: VS Code extension is coming soon.
 
 ```bash
 trie init          # Set up Trie in your project
-trie scan          # Analyze codebase with intelligent skill selection
+trie tell          # Report incidents (extracts decisions, facts, blockers)
 trie status        # View project health and memory stats
 trie learn         # Train Trie from history or feedback
 trie gotcha        # Predict problems with current changes
@@ -466,6 +535,8 @@ tmux new -s trie-watch && trie watch  # Detach: Ctrl+B, D
 
 ### Scan Behavior
 
+> **Note**: Trie no longer uses traditional "scans". Instead, it extracts structured signals from incidents, commits, and conversations. Configuration below is for legacy compatibility.
+
 Create .trie/config.json:
 
 ```json
@@ -524,11 +595,11 @@ Trie sends notifications to Slack for team collaboration:
 ```
 
 **What Trie sends to Slack:**
-- Scan completion notifications with issue counts
-- Critical security alerts (immediate)
+- Decision extractions from incidents
+- Active blockers  
+- Risk predictions from gotcha
 - Daily/weekly team summaries
-- Escalation notifications for overdue issues
-- Bulk fix notifications
+- Critical decision changes
 
 ## CI/CD Integration
 
@@ -539,9 +610,9 @@ Trie sends notifications to Slack for team collaboration:
 trie ci github
 
 # Creates .github/workflows/trie.yml with:
-# - Full codebase scan
+# - Decision ledger queries
 # - Memory caching for speed
-# - SARIF upload for GitHub Security tab
+# - Risk prediction on PRs
 ```
 
 ### Custom CI
@@ -549,7 +620,10 @@ trie ci github
 ```bash
 # In your CI pipeline
 npm install -g trie
-trie scan --output=sarif > trie-results.sarif
+# Query decision ledger for risks
+trie gotcha
+# Check memory for related incidents
+trie memory search "deployment"
 ```
 
 ## Memory System
@@ -567,7 +641,6 @@ Performance over time
 Global patterns stored in ~/.trie/memory/:
 
 Patterns that apply across projects  
-Skill effectiveness data  
 Your personal coding patterns
 
 ### Memory Management
@@ -588,82 +661,17 @@ 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.
+**Trie not finding issues**: You haven't taught Trie about your specific patterns yet. Use `trie tell` to report incidents and build your decision ledger.
 
-Scans are slow: Reduce concurrency with --max-concurrency=2 or exclude large directories in config.
+**Memory queries returning empty**: The warm storage is empty. Report some incidents with `trie tell` or run `trie learn` to extract from git history.
 
-Too many false positives: Use trie bad to train Trie, and consider adjusting scout sensitivity in config.
+**Query tools not working**: Make sure you've initialized Trie with `trie init` and have ANTHROPIC_API_KEY set for signal extraction.
 
-Hooks not working: Reinstall with trie init. Make sure you have write permissions to .git/hooks/.
+**Hooks not working**: Reinstall with `trie init`. Make sure you have write permissions to .git/hooks/.
 
 ### Getting Help
 - Issues: [Report bugs and request features](https://x.com/louiskishfy)