memorylink 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to MemoryLink will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.5.1] - 2025-12-19
+
+### Added
+- **Stats Recommendations**: Contextual suggestions based on Buddy-Check metrics
+  - High RED rate warnings (>10%)
+  - High override rate suggestions (>20%)
+  - Low trust level recommendations (>50%)
+  - Frequent issue detection (>30% of runs)
+- **Verbose Score Breakdown**: Detailed component breakdown for smart filtering
+  - Shows trust, status, recency, file, and task scores
+  - Use `--smart --verbose` to see breakdown
+- **Stats Schema Versioning**: Version and period fields in stats output
+  - `schemaVersion: '1.5.0'` included in all formats
+  - `period: { start, end }` for time range tracking
+  - Safe for external system ingestion
+- **Optional Recommendations**: `--no-recommendations` flag for pure metrics mode
+
+### Enhanced
+- **Edge Case Handling**: Improved handling of zero-run scenarios
+- **Period Start Update**: `--since` filter correctly updates period start time
+- **Recommendation Logic**: Better thresholds and actionable messages
+
+### Documentation
+- **Cursor AI Integration Guide**: Complete guide for integrating Buddy-Check into Cursor AI
+- **Release Documentation**: Comprehensive release notes and validation results
+
+---
+
+## [1.5.0] - 2025-12-19
+
+### Added
+- **Real-Time Checkpoints** (v1.5 Phase 1)
+  - Create memory snapshots with Git metadata
+  - List and compare checkpoints
+  - Restore checkpoints with safety confirmation
+- **Agent Locking** (v1.5 Phase 1)
+  - Acquire/release locks for multi-agent coordination
+  - Lock status checking and renewal
+  - Preflight integration (warns on active locks)
+- **Smart Filtering** (v1.5 Phase 1)
+  - Weighted scoring (trust, status, recency, file, task)
+  - Configurable weights in config.json
+  - Threshold-based filtering
+- **Project Scoping** (v1.5 Phase 2)
+  - Associate memory with project scopes
+  - Filter context by scope
+  - List all scopes with statistics
+  - Scope validation (max 50 chars, alphanumeric + dash/underscore/slash)
+- **Enhanced Observability** (v1.5 Phase 2)
+  - Aggregate metrics from observability.log
+  - Multiple output formats (text, JSON, CSV, Markdown)
+  - Run counts, status distribution, trust levels, issue types
+
+### Enhanced
+- **Checkpoint Restore**: Safe restore with temp file and manual confirmation
+- **Lock Renew**: Extend lock timeout during long sessions
+- **Scopes List**: List all scopes with counts and statistics
+- **Scope Validation**: Validate scope format in memory command
+- **Configurable Smart Weights**: Configure smart filtering weights in config.json
+
+---
+
+## [1.4.0] - 2025-12-19
+
+### Added
+- **Buddy-Check System** (v1.4)
+  - Preflight checks (before agent runs)
+  - Postflight checks (after agent changes)
+  - Status reporting (GREEN/YELLOW/RED)
+  - Schema validation, security checks, referential integrity
+- **Schema Evolution** (v1.4)
+  - New `MemoryRecord` type with enhanced fields
+  - `schemaVersion`, `recordVersion`, `sensitivity`, `trustLevel`, `status`
+  - `sourceType`, `provenance`, `expiresAt`, `incident`
+- **Migration System**: `memorylink migrate --to 1.4` command
+- **Observability Log**: `.memorylink/observability.log` for Buddy-Check telemetry
+- **Override Logging**: `.memorylink/overrides.log` for human overrides
+- **Developer vs Enterprise Modes**: Configuration in `.memorylink/config.json`
+- **VS Code Integration**: Status bar, sidebar, AI action hooks
+- **CI Integration**: GitHub Actions example for preflight checks
+
+### Enhanced
+- **Backward Compatibility**: Automatic normalization of v1.3 records to v1.4
+- **JSON/TOON Adapter**: Pluggable formatter for memory records
+
+---
+
+## [1.3.0] - 2025-12-19
+
+### Added
+- **MCP Server**: Model Context Protocol server for AI integration
+- **Vector Search**: Semantic search capabilities
+- **Tag Intelligence**: Enhanced tag management
+- **Batch Commits**: Efficient batch operations
+- **Auto-Capture**: Automatic memory capture
+- **Tree-sitter**: Python/Go parsing support
+- **VS Code Extension**: Basic scaffold
+
+---
+
+## [1.0.0] - 2025-12-19
+
+### Added
+- **Core Memory Management**: JSONL-based memory storage
+- **Learning Management**: Success/failure tracking
+- **Search**: Tag and file-based search
+- **Context Retrieval**: Intelligent context gathering
+- **File Protection**: Protected files list
+- **Change Tracking**: File change audit trail
+- **Code Structure**: Code snippet and structure tracking
+- **Quality Validation**: Memory quality checks
+- **Templates**: Memory entry templates
+- **Export**: Data export functionality
+- **Status & Doctor**: System health checks
+- **Roadmap**: Feature roadmap tracking
+- **Patterns**: Pattern recognition
+
+---
+
+**Legend**:
+- `Added`: New features
+- `Enhanced`: Improvements to existing features
+- `Fixed`: Bug fixes
+- `Deprecated`: Features that will be removed
+- `Removed`: Removed features
+- `Security`: Security improvements

package/CHATGPT_GAP_ANALYSIS.md

@@ -0,0 +1,286 @@
+# ChatGPT Gap Analysis: What's Missing
+
+**Date**: December 15, 2025  
+**Source**: ChatGPT v2 Validation  
+**Status**: Gap Analysis Complete
+
+---
+
+## 🎯 PHILOSOPHICAL DIFFERENCE
+
+### What We Built (v1.2):
+**"Code Structure Memory"** - Automatic AST parsing, dependency graphs, impact prediction  
+**Approach**: Code intelligence (like Chinese tools)
+
+### What ChatGPT Recommends:
+**"Decision-Aware Structure Memory"** - Human-verified notes, decision-to-file links, observed impacts  
+**Approach**: Decision memory (unique to MemoryLink)
+
+### Key Insight:
+- **Chinese Tools**: "Here is how the code is connected" (WHAT)
+- **MemoryLink Should Be**: "Here is how OUR DECISIONS interact with the codebase" (WHY)
+
+---
+
+## 📊 DETAILED GAP ANALYSIS
+
+### 1. Structure Memory Type
+
+#### What We Have:
+```typescript
+// Automatic AST parsing
+graph.files.get("src/auth.ts") // Auto-extracted from code
+graph.dependencies.get("src/auth.ts") // Auto-detected imports
+```
+
+#### What ChatGPT Wants:
+```json
+{
+  "type": "structure_note",
+  "subject": "src/auth.ts",
+  "connected_files": ["src/middleware/authGuard.ts"],
+  "warning": "Changes here affect all protected APIs",
+  "confidence": "high"
+}
+```
+
+**Gap**: ❌ Missing human-verified structure notes  
+**Impact**: Medium - We have automatic, but not human-verified layer
+
+---
+
+### 2. Decision-to-File Linking
+
+#### What We Have:
+```json
+{
+  "type": "decision",
+  "details": "JWT validation centralized",
+  "tags": ["auth"]
+}
+// File connection is implicit (via tags/search)
+```
+
+#### What ChatGPT Wants:
+```json
+{
+  "type": "decision_link",
+  "decision": "JWT validation centralized",
+  "files": ["src/auth.ts"],
+  "reason": "Avoid duplicate token logic"
+}
+```
+
+**Gap**: ❌ Missing explicit decision-to-file links  
+**Impact**: High - Decisions exist but not explicitly linked to files
+
+---
+
+### 3. Observed Impacts
+
+#### What We Have:
+```json
+{
+  "type": "change_impact",
+  "file": "src/auth.ts",
+  "impact": {
+    "direct_dependents": 3,
+    "indirect_dependents": 8,
+    "breaking_changes": ["Docker setup"]
+  }
+}
+// This is PREDICTION based on graph
+```
+
+#### What ChatGPT Wants:
+```json
+{
+  "type": "impact_observed",
+  "change": "Moved JWT secret to env",
+  "observed_issues": ["Docker build failed", "Local dev broken"],
+  "resolution": "Added .env.example",
+  "severity": "high"
+}
+// This is REALITY - what actually happened
+```
+
+**Gap**: ❌ Missing observed impacts (we only have predictions)  
+**Impact**: High - Predictions vs Reality is important distinction
+
+---
+
+### 4. Risk Command
+
+#### What We Have:
+```bash
+memorylink impact src/auth.ts --change "Moving JWT to env var"
+# Shows: Predictions based on graph
+```
+
+#### What ChatGPT Wants:
+```bash
+memorylink risk src/auth.ts
+# Shows: Risk based on RECORDED truth (structure notes, decision links, observed impacts)
+```
+
+**Gap**: ⚠️ Similar but different philosophy  
+**Impact**: Medium - We have `impact` but not `risk` (recorded truth only)
+
+---
+
+## 🔄 WHAT WE HAVE vs. WHAT'S MISSING
+
+| Feature | What We Built | What ChatGPT Wants | Gap? |
+|---------|---------------|-------------------|------|
+| **Structure Analysis** | ✅ Automatic AST parsing | ⚠️ Human-verified notes | ⚠️ Missing human layer |
+| **Decision Storage** | ✅ Decisions exist | ❌ Explicit file links | ❌ Missing `decision_link` |
+| **Impact Tracking** | ✅ Predictions (graph-based) | ❌ Observed impacts | ❌ Missing `impact_observed` |
+| **Risk Assessment** | ✅ `impact` command | ⚠️ `risk` command (truth-only) | ⚠️ Different philosophy |
+| **Commands** | ✅ `graph build`, `graph-query`, `impact` | ❌ `annotate`, `link-decision`, `log-impact`, `risk` | ❌ Missing 4 commands |
+
+---
+
+## 💡 CHATGPT'S RECOMMENDATION
+
+### Add (Minimal, Safe):
+1. ✅ `structure_note` type - Human-verified structural notes
+2. ✅ `decision_link` type - Explicit decision-to-file connections
+3. ✅ `impact_observed` type - Recorded impacts (what actually happened)
+4. ✅ 4 new commands: `annotate`, `link-decision`, `log-impact`, `risk`
+
+### Keep (What We Have):
+- ✅ Automatic AST parsing (useful)
+- ✅ Dependency graphs (useful)
+- ✅ Impact predictions (useful)
+
+### Philosophy:
+- **Hybrid Approach**: Automatic + Human-verified = Complete picture
+- **Don't Remove**: Keep automatic features
+- **Add Layer**: Human-verified for trust and determinism
+
+---
+
+## 🎯 IMPLEMENTATION DECISION
+
+### Option 1: Keep Current (Automatic Only)
+- ✅ Already implemented
+- ✅ Works well
+- ❌ Missing human-verified layer
+- ❌ Missing decision-to-file links
+- ❌ Missing observed impacts
+
+### Option 2: Add Human-Verified Layer (ChatGPT's Recommendation)
+- ✅ Complements automatic features
+- ✅ Maintains MemoryLink's "WHY" focus
+- ✅ 1-2 weeks development
+- ✅ 3 new types + 4 new commands
+
+### Option 3: Hybrid (RECOMMENDED)
+- ✅ Keep automatic AST parsing (v1.2)
+- ✅ Add human-verified structure notes
+- ✅ Add decision-to-file links
+- ✅ Add observed impacts
+- ✅ Show both in `get-context` and `risk` commands
+- ✅ Best of both worlds
+
+---
+
+## 📋 WHAT TO IMPLEMENT
+
+### Phase 1: Add Missing Types (1 week)
+
+1. **Add `structure_note` to memory.log**:
+   - Human-verified structural notes
+   - Complements automatic AST parsing
+
+2. **Add `decision_link` to memory.log**:
+   - Explicit decision-to-file connections
+   - Links existing decisions to files
+
+3. **Add `impact_observed` to learnings.log**:
+   - Recorded impacts (what actually happened)
+   - Complements impact predictions
+
+### Phase 2: Add Commands (1 week)
+
+1. **`memorylink annotate <file>`**
+   - Create structure_note entries
+   - `--connect <files>` - Connected files
+   - `--warning <text>` - Warnings
+
+2. **`memorylink link-decision <decision-id> <file>`**
+   - Link existing decisions to files
+   - Creates decision_link entry
+
+3. **`memorylink log-impact`**
+   - Log observed impacts after incidents
+   - `--change`, `--files`, `--issue`, `--resolution`
+
+4. **`memorylink risk <file>`**
+   - Show risk based on recorded truth
+   - Combines: structure notes + decision links + observed impacts
+   - No predictions, only facts
+
+### Phase 3: Integration (3-5 days)
+
+1. Update `get-context` to include:
+   - Structure notes
+   - Decision links
+   - Observed impacts
+
+2. Update `impact` command to show:
+   - Predictions (from graph) AND
+   - Observed impacts (from logs)
+
+3. Update `doctor` to check:
+   - Structure notes freshness
+   - Decision links completeness
+
+---
+
+## 🚨 CRITICAL WARNING FROM CHATGPT
+
+> "Do NOT turn MemoryLink into a code intelligence engine. If you do that, you will lose simplicity, trust, determinism, and your core advantage."
+
+**What This Means**:
+- ✅ Keep automatic features (they're useful)
+- ✅ Add human-verified layer (this is the differentiator)
+- ❌ Don't remove simplicity
+- ❌ Don't break trust and determinism
+
+---
+
+## 📊 GAP CLOSURE ASSESSMENT
+
+### Current State:
+- ✅ Automatic code structure: 100% complete
+- ❌ Human-verified structure: 0% complete
+- ❌ Decision-to-file links: 0% complete
+- ❌ Observed impacts: 0% complete
+
+### After Adding Human Layer:
+- ✅ Automatic code structure: 100% complete
+- ✅ Human-verified structure: 100% complete
+- ✅ Decision-to-file links: 100% complete
+- ✅ Observed impacts: 100% complete
+- ✅ **Gap Closure**: 70-75% → 90-92%
+
+---
+
+## 🎯 FINAL RECOMMENDATION
+
+**Implement Hybrid Approach**:
+1. Keep automatic AST parsing (v1.2) - it's useful
+2. Add human-verified layer (ChatGPT's recommendation) - it's the differentiator
+3. Show both in commands - best of both worlds
+4. Maintain simplicity - don't break what works
+
+**Estimated Effort**: 1-2 weeks  
+**Impact**: High (closes gap to 90-92%)  
+**Risk**: Low (additive, doesn't break existing)
+
+---
+
+**Status**: ✅ Gap Analysis Complete  
+**Next Step**: Wait for other AI responses, then implement consensus
+

package/CHATGPT_V2_ANALYSIS.md

@@ -0,0 +1,109 @@
+# ChatGPT v2 Analysis: Decision-Aware Structure Memory
+
+**Date**: December 15, 2025  
+**Status**: ✅ Validated and Stored
+
+---
+
+## 🎯 KEY INSIGHT FROM CHATGPT
+
+**Philosophical Correction**: MemoryLink should focus on **"Decision-Aware Structure Memory"** not just "Code Structure Memory"
+
+**Core Differentiator**:
+- **Chinese Tools**: "Here is how the code is connected" (WHAT)
+- **MemoryLink**: "Here is how OUR DECISIONS interact with the codebase" (WHY)
+
+---
+
+## ✅ WHAT CHATGPT VALIDATES
+
+1. ✅ Gap identification is correct (missing structural relationships)
+2. ✅ Chinese tools DO excel at structure
+3. ✅ MemoryLink should NOT become code intelligence engine
+4. ✅ Should maintain simplicity, trust, determinism
+5. ✅ Competitive advantage: "WHY" vs "WHAT"
+
+---
+
+## 🔄 WHAT WE HAVE vs. WHAT CHATGPT WANTS
+
+### What We Built (v1.2):
+- ✅ Automatic AST parsing
+- ✅ Automatic dependency graphs
+- ✅ Impact prediction
+- ✅ `graph build`, `graph-query`, `impact` commands
+
+### What ChatGPT Recommends:
+- ⚠️ Human-verified structure notes (we have automatic)
+- ❌ `decision_link` type (we have decisions, but not file links)
+- ❌ `impact_observed` type (we have predictions, not observed)
+- ⚠️ `risk` command (we have `impact`, similar but different)
+
+---
+
+## 💡 CHATGPT'S RECOMMENDATION
+
+### 3 New Memory Types:
+1. **`structure_note`** - Human-verified structural notes
+2. **`decision_link`** - Explicit decision-to-file connections
+3. **`impact_observed`** - Recorded impacts (what actually happened)
+
+### 4 New Commands:
+1. **`annotate`** - Human structure notes
+2. **`link-decision`** - Link decisions to files
+3. **`log-impact`** - Log observed impacts
+4. **`risk`** - Show risk based on recorded truth
+
+---
+
+## 📊 GAP CLOSURE
+
+**Before**: 70-75% solved  
+**After adding decision-aware structure**: 90-92% solved
+
+**Remaining 8-10%**: Don't need to be solved by MemoryLink (MCP handles injection, models improve)
+
+---
+
+## 🎯 DECISION NEEDED
+
+**Option 1**: Keep automatic AST parsing only (current v1.2)
+- ✅ Already implemented
+- ✅ Works well
+- ❌ Missing human-verified layer
+
+**Option 2**: Add human-verified layer (ChatGPT's recommendation)
+- ✅ Complements automatic features
+- ✅ Maintains MemoryLink's "WHY" focus
+- ✅ 1-2 weeks development
+
+**Option 3**: Hybrid approach (BEST)
+- ✅ Keep automatic AST parsing
+- ✅ Add human-verified structure notes
+- ✅ Show both in `get-context` and `risk` commands
+- ✅ Best of both worlds
+
+---
+
+## 🚨 CRITICAL WARNING FROM CHATGPT
+
+> "Do NOT turn MemoryLink into a code intelligence engine. If you do that, you will lose simplicity, trust, determinism, and your core advantage."
+
+**What This Means**: Keep automatic features, but add human layer for trust and determinism.
+
+---
+
+## 📋 NEXT STEPS
+
+1. ✅ **Stored ChatGPT's response** in MemoryLink
+2. 🔄 **Wait for other AI responses** (if any)
+3. 🔄 **Compare all responses** and find consensus
+4. 🔄 **Decide**: Add human-verified layer or keep automatic only?
+5. 🔄 **Implement**: If adding, follow minimal approach (3 types, 4 commands)
+
+---
+
+**Status**: ✅ Analysis Complete  
+**Priority**: Medium (complements existing, doesn't replace)  
+**Recommendation**: Hybrid approach (automatic + human-verified)
+