memorylink 1.0.0

package/docs/PERPLEXITY_AI_ANALYSIS.md

@@ -0,0 +1,285 @@
+# Perplexity AI Analysis: MemoryLink Structure Memory Implementation
+
+**Date**: December 14, 2025  
+**Source**: Perplexity AI Comprehensive Analysis  
+**Status**: ✅ Stored in MemoryLink
+
+---
+
+## 📊 Executive Summary
+
+Perplexity AI validated the gap analysis and provided a concrete, minimal implementation plan for adding code structure memory, change impact prediction, and team pattern detection to MemoryLink without changing the core architecture.
+
+---
+
+## ✅ Validation of Missing Dimensions
+
+### 1. Code Structure Memory ❌
+- **Missing**: Internal code graph (files, symbols, dependencies, callers)
+- **Current State**: No persistent understanding of imports/exports graph
+- **Impact**: Cannot answer "These files depend on this module"
+
+### 2. Change Impact Memory ❌
+- **Missing**: Explicit "impact map" per change
+- **Current State**: Tracks changes and learnings, but not impact relationships
+- **Impact**: Cannot predict "this change impacts Y files and Z workflows"
+
+### 3. Team Pattern Memory ❌
+- **Missing**: Aggregated team-level patterns from learnings
+- **Current State**: Tracks SUCCESS/FAILED learnings, but doesn't aggregate into patterns
+- **Impact**: Cannot learn "your team usually handles errors like this"
+
+**Conclusion**: MemoryLink remembers **what** and **how**, but not **where it lives** and **how it connects**.
+
+---
+
+## 🎯 v1.0 vs v1.1+ Roadmap
+
+### For v1.0 Early Adopters
+- ✅ **Not a blocker**: Current feature set is useful and differentiated
+- ✅ **Big upside**: Code structure features are valuable but not required
+- ✅ **Can ship**: Local, Git-native, decision/learning memory is sufficient
+
+### For Global Competitiveness
+- ⚠️ **Missing 20%**: Code structure + impact + patterns are the gap
+- ⚠️ **Next major phase**: v1.1+/v2.0 should absolutely include these
+- ⚠️ **Competitive need**: To be "team knowledge + codebase intelligence" tool
+
+**Recommendation**: v1.0 can ship without these, but v1.1+/v2.0 roadmap should include them.
+
+---
+
+## 🏗️ Architecture Compatibility
+
+### ✅ Current Architecture Supports This
+
+**JSONL + Git design can easily store:**
+- `type: "code_structure"` entries
+- `type: "change_impact"` entries
+- `type: "team_pattern"` entries
+
+**Additional derived files:**
+- `.memorylink/code-graph.json`
+- `.memorylink/team-patterns.json`
+
+**No core architecture change needed**, just add:
+- **Scanner**: `map-codebase` that computes code graph
+- **Predictor**: `predict-impact` that uses graph to emit change_impact entries
+- **Analyzer**: `detect-patterns` that mines learnings.log for patterns
+
+**Conclusion**: Base architecture is compatible with this direction.
+
+---
+
+## 📋 Concrete Implementation Plan
+
+### 1. `memorylink map-codebase`
+
+**Goal**: Build and store code graph for dependency tracking
+
+**Data Format**:
+```jsonc
+// .memorylink/code-graph.json
+{
+  "files": {
+    "src/auth.ts": {
+      "imports": ["src/config.ts", "src/utils/jwt.ts"],
+      "imported_by": ["src/middleware/authGuard.ts", "src/routes/login.ts"]
+    }
+  },
+  "generated_at": "2025-12-14T17:30:00Z"
+}
+```
+
+**CLI Command**:
+```bash
+memorylink map-codebase \
+  [--root=src] \
+  [--extensions=.ts,.tsx,.js,.jsx] \
+  [--output=.memorylink/code-graph.json]
+```
+
+**Implementation**:
+- Walk project files under `--root` with allowed extensions
+- Parse imports per language (TS/JS: `import/require`, Python: `import/from`)
+- Resolve relative imports to normalized paths
+- Build `imports` and `imported_by` (reverse edges)
+- Write atomically (temp + rename)
+
+**Start simple in v1.1, improve parsing later**
+
+---
+
+### 2. `memorylink predict-impact`
+
+**Goal**: Show what files are affected by changes
+
+**Output Example**:
+```bash
+memorylink predict-impact src/auth.ts
+
+File: src/auth.ts
+
+Direct dependents:
+- src/middleware/authGuard.ts
+- src/routes/login.ts
+
+Transitive impact (2 hops):
+- src/routes/profile.ts
+
+Suggested attention areas:
+- Tests: tests/auth.spec.ts
+- Config: src/config.ts
+```
+
+**Internal Logic**:
+- Read `.memorylink/code-graph.json`
+- Get `imported_by` (1 hop) for target file
+- Optional BFS to depth 2 for transitive impact
+- Heuristics: Mark `tests/`, `config/`, `*.config.*` files
+
+**Optional Logging**:
+```bash
+memorylink predict-impact src/auth.ts --log
+```
+Appends `change_impact` entry to `memory.log`
+
+---
+
+### 3. `memorylink detect-patterns`
+
+**Goal**: Aggregate learnings into team best practices
+
+**Data Format**:
+```jsonc
+// .memorylink/team-patterns.json
+{
+  "patterns": [
+    {
+      "id": "pattern_001",
+      "type": "team_pattern",
+      "area": "error_handling",
+      "pattern": "Use try/catch with AppError in API routes.",
+      "success_rate": 0.92,
+      "occurrences": 24,
+      "tags": ["api", "errors"]
+    }
+  ],
+  "generated_at": "2025-12-14T18:00:00Z"
+}
+```
+
+**CLI Command**:
+```bash
+memorylink detect-patterns \
+  [--min-occurrences=3] \
+  [--output=.memorylink/team-patterns.json]
+```
+
+**Implementation**:
+- Read `learnings.log`, filter `status=SUCCESS`
+- Group by tags and/or n-gram signatures
+- Compute `success_rate` (success / total attempts)
+- Save patterns with `occurrences >= min-occurrences`
+- Surface in `get-context` and `patterns` command
+
+**Start with simple tag/text grouping, refine later**
+
+---
+
+## 🔗 Integration into Existing Flows
+
+### Enhanced `get-context`
+
+When building context:
+
+1. Rules (from `rules.md` or `memory.log` `type=rule/preference`)
+2. Decisions/learnings relevant to tags or files
+3. **New optional sections**:
+   - Code structure (if `--file=...` passed, show imports/imported_by)
+   - Change impacts (`change_impact` entries filtered by tags)
+   - Team patterns (matching tags from `team-patterns.json`)
+
+**Example**:
+```bash
+memorylink get-context --file src/auth.ts --tag auth
+```
+
+**Output includes**:
+```text
+# Code Structure
+
+src/auth.ts:
+- Imports: src/config.ts, src/utils/jwt.ts
+- Used by: src/middleware/authGuard.ts, src/routes/login.ts
+
+# Team Patterns (auth/errors)
+
+- Error handling in API:
+  Use try/catch with AppError (92% success).
+```
+
+### `doctor` Updates
+
+- Check that `code-graph.json` and `team-patterns.json` are parseable
+- Warn if out of date (older than X days or last Git commit)
+
+---
+
+## 📅 Development Order
+
+1. **`map-codebase` + `code-graph.json`**
+   - Simple, standalone, immediately useful
+
+2. **`predict-impact` using `code-graph.json`**
+   - Quick heuristic impact analysis + optional logging
+
+3. **`detect-patterns` using `learnings.log`**
+   - Start with simple tag/text grouping, refine later
+
+4. **Hook into `get-context`**
+   - Show structure/impact/patterns when `--file` or relevant tags provided
+
+**All fits existing JSONL + derived-files architecture and can be extended later without breaking v1.0**
+
+---
+
+## 🎯 Competitive Positioning
+
+### MemoryLink's Unique Angle
+
+**Current Strengths**:
+- Local, Git-native, multi-AI, team-oriented memory
+- Tracks decisions + learnings + enforcement
+
+**With Structure Layer Added**:
+- Code structure memory (like Sourcegraph Cody but local)
+- Change impact prediction (like Augment Code)
+- Team pattern detection (like GitHub Copilot)
+- **Result**: "Project brain that knows both what we decided and how the code connects"
+
+### Competitive Comparison
+
+| **Tool** | **Focus** | **MemoryLink Advantage** |
+|----------|-----------|--------------------------|
+| Mem0/Supermemory | Semantic content + conversation | Code graph + Git-native |
+| Cody/Sourcegraph | Code graph + search | Git-native memory tracking |
+| GitHub Copilot | Team patterns | Local-first + decision memory |
+
+**Conclusion**: No one is truly "unbeatable" across all dimensions; MemoryLink just hasn't built the structure side yet.
+
+---
+
+## ✅ Next Steps
+
+1. ✅ **Analysis stored** in MemoryLink as learnings and decisions
+2. 🔄 **Design JSON formats** for `code-graph.json` and `team-patterns.json`
+3. 🔄 **Design CLI behavior** for `map-codebase`, `predict-impact`, `detect-patterns`
+4. 🔄 **Plan v1.1 implementation** following development order
+
+---
+
+**Source**: Perplexity AI Comprehensive Analysis  
+**Stored**: December 14, 2025  
+**Status**: ✅ Validated and stored in MemoryLink
+

package/docs/PERPLEXITY_AI_CLARIFICATION.md

@@ -0,0 +1,57 @@
+# Perplexity AI Clarification – 33% Risk Focus
+
+**Date**: December 15, 2025  
+**Context**: Response to AI Panel Clarification Request (67% vs 33% split)  
+**Position**: Ship now, pre-announce v1.5; prioritize integrations over Tree-sitter/dashboard pre-launch.
+
+## Key Findings
+- **Abandonment Risk (rough)**  
+  - JS/TS + CLI: ~10–15% without Tree-sitter/dashboard.  
+  - Python/Go + CLI: ~30–40% (structure feels half-there).  
+  - Visual-first, non-CLI: ~40–60% without dashboard/IDE view.  
+  - Weighted early adopters: ~20–25% churn from “JS/TS-only, CLI-first, no dashboard”.
+
+- **Time-to-Failure**  
+  - Polyglot teams: first serious backend task (same day/1–2 sessions) shows missing Python/Go structure.  
+  - Visual-first: immediate bounce at “CLI only”.  
+  - JS/TS CLI users: no failure; just limited cross-stack graph.
+
+- **Mitigations That Work**  
+  - Label clearly: “JS/TS optimized; Python/Go structure in v1.5 (~2–4 weeks)” → can cut non-JS abandonment by ~30–40%.  
+  - Pre-announce v1.5 in a visible section (not buried).  
+  - Minimal read-only web viewer or VS Code sidebar reduces visual-first abandonment by ~15–20%.
+
+- **Market Now vs 60 Days**  
+  - Shipping 60 days later is meaningfully worse; biggest adoption ramp is often in first 2–4 weeks post-launch.  
+  - Speed > day-one multi-language completeness; many devtools launched narrow then expanded (Mem0, Supermemory, early Cody).
+
+- **User Intent Mix (likely early users)**  
+  - Stack: 60–70% JS/TS, 20–30% Python, 10–20% others.  
+  - UX: 70–80% CLI-comfortable; 20–30% visual-first.  
+  - Implies initial risk is manageable; the most harmed segments are not the majority of first users.
+
+- **What Vendors Prioritize Now**  
+  - Hot: MCP-style integrations, VS Code/plugins, “one-click context”.  
+  - Embeddings/HTTP APIs for ease of integration.  
+  - Sourcegraph/Cody: multi-language graph + IDE UX.  
+  - Takeaway: Deferring Tree-sitter a few weeks is acceptable; deferring major-tool integration is riskier.
+
+- **Minimal Credible Commitments (if shipping now)**  
+  - Messaging: “JS/TS optimized today; Python/Go structure + basic dashboard targeted for v1.5 (2–4 weeks).”  
+  - Internal triggers: start Tree-sitter at ≥100 Python/Go project signals; start dashboard at ≥50 explicit UI requests.  
+  - Public roadmap with v1.5 items listed.
+
+- **Where Tree-sitter/Dashboard Are Decisive vs Not**  
+  - Tree-sitter decisive: polyglot teams expecting Cody-like impact; agents asked about Python files give weak answers.  
+  - Tree-sitter non-decisive: JS/TS-only repos or mostly frontend work.  
+  - Dashboard decisive: leads/EMs or compliance stakeholders who won’t use CLI.  
+  - Dashboard non-decisive: solo/small CLI/VSC users; they value MCP + docs more.
+
+## Overall Guidance (Perplexity)
+- **Launch v1.3 now.**  
+- **Do not delay** for Tree-sitter or full dashboard.  
+- **Yes, pre-announce v1.5** (2–4 weeks) for Python/Go structure + lightweight read-only dashboard.  
+- **Focus pre-launch** on website, docs, one good demo, and VS Code/MCP polish.  
+- Use the proposed thresholds; they are reasonable.
+
+

package/docs/PERPLEXITY_AI_STRATEGIC_VALIDATION.md

@@ -0,0 +1,288 @@
+# Perplexity AI Strategic Validation - Launch Strategy
+
+**Date**: December 15, 2025  
+**Source**: Perplexity AI Strategic Questions Response  
+**Status**: ✅ Stored in MemoryLink
+
+---
+
+## 📊 EXECUTIVE SUMMARY
+
+Perplexity AI provides **direct strategic answers** treating v1.3 as already built and stable. Key recommendation: **Ship v1.3 now, don't delay for Tree-sitter or dashboard, but DO add minimal VS Code extension + website pre-launch**.
+
+**Key Insight**: "With this, the concept is solid, the launch is realistic, and future work is about depth and reach, not fixing fundamental design gaps."
+
+---
+
+## 🎯 QUESTION 1: PRE-LAUNCH vs POST-LAUNCH FEATURES
+
+### Tree-sitter / Multi-Language Structure
+
+**Answer: Launch WITHOUT it (medium risk, not critical)**
+
+**Why:**
+- Many early adopters will be JS/TS-heavy or will still see value from decisions/learnings/rules + basic graph
+- However, if primary initial users are backend-heavy (Python/Go), missing structure will make "code graph" story feel incomplete
+
+**Recommendation:**
+- Ship with **v1.3 now**, **do not delay launch** for Tree-sitter
+- Make Tree-sitter **top priority in v2.0** (first language: Python)
+- Be honest in marketing: "JS/TS full structure; other languages coming."
+
+---
+
+### Web Dashboard
+
+**Answer: Not critical for v1.x launch**
+
+**Why:**
+- Devs can get value via CLI + MCP + IDE integration
+- A simple web UI is more about **widening the audience** later (leads, managers, non-CLI users)
+
+**Recommendation:**
+- Ship without full dashboard
+- Make **very simple web dashboard** the second priority in v2.0
+
+---
+
+## 🔌 QUESTION 2: INTEGRATION STRATEGY (MCP vs Native Plugins)
+
+### Current Situation:
+- MCP for Claude/Cursor gives **excellent first-class integration** in some of the best dev tools today
+- For others:
+  - ChatGPT / Copilot: manual injection is **acceptable** at launch, especially for devs
+  - VS Code: having at least a **minimal extension** that wraps your MCP/CLI is a big UX win
+
+**Recommendation:**
+
+**Pre-launch:**
+- MCP server (done) ✅
+- **Minimal VS Code extension** that:
+  - Runs `get-context` for current file
+  - Shows MemoryLink info in a sidebar
+
+**Post-launch:**
+- Explore IntelliJ plugin
+- Deeper ChatGPT "MemoryLink helper" prompts
+- Copilot instructions
+
+**Key Insight**: "Manual injection is fine for initial users; lack of any VS Code integration will hurt more than lack of ChatGPT/Copilot plugins."
+
+---
+
+## 🤖 QUESTION 3: AGENT-DRIVEN WORLD - Is "Good Enough" Enough?
+
+**Answer: YES - "Good enough" is sufficient for launch**
+
+**In agent-driven workflows, "good enough" means:**
+- Agents can reliably get **rules + relevant context** for the current file/task
+- Not that you support every language and integration from day one
+
+**For MemoryLink, the critical features for agent success are:**
+
+1. ✅ Stable, fast `get-context` (rules first, then decisions/learnings, then structure/patterns where available)
+2. ✅ MCP / extension so at least some agents can pull context automatically
+3. ✅ Clear rules about protected files and secrets, so agents don't break things
+
+**Tree-sitter and dashboard improve results, but agents can still be very useful with your current JS/TS graph and vector search.**
+
+**Recommendation:**
+
+**For launch, "good enough" is:**
+- v1.3 features + MCP + basic VS Code extension + solid docs
+
+**"Feature-complete" across all languages and tools is NOT required** to avoid abandonment, as long as:
+- The first experience shows real value on supported stacks
+- You clearly communicate what is supported today vs coming next
+
+---
+
+## 💰 QUESTION 4: BUSINESS MODEL (Free / Pro / Enterprise)
+
+### 🆓 FREE Should Include:
+
+- Core memory (memory/logging of decisions, learnings, changes)
+- Search (keyword + basic semantic)
+- Git integration, protected files, secret detection
+- Basic code graph for JS/TS
+- MCP and CLI
+
+**Purpose**: Makes the "core project brain" accessible and drives adoption
+
+---
+
+### 💼 PRO (e.g., $10–15/user/month) Can Include:
+
+- Multi-language code structure (Tree-sitter)
+- Team patterns & analytics (pattern detection, success rates)
+- Web dashboard (per-repo)
+- Advanced filters, timelines, and impact reports
+- Priority support
+
+**Purpose**: Advanced features for teams
+
+---
+
+### 🏢 ENTERPRISE Can Include:
+
+- Org-level / multi-repo memory and analytics
+- SSO, RBAC, audit exports, policy controls
+- On-prem or VPC deployment, encrypt-at-rest
+- Custom integrations and SLAs
+
+**Purpose**: Enterprise compliance and scale
+
+---
+
+### Competitive Positioning:
+
+**You compete with "free built-in memory" (e.g., Cursor) by:**
+
+- Being **cross-tool, cross-AI, and Git-native**, not tied to one IDE
+- Offering **compliance, audit, and enforcement** features they don't
+
+---
+
+## 🌍 QUESTION 5: WEBSITE & MARKETING
+
+**Answer: A website is CRITICAL for launch**
+
+**Why:**
+- Without it, discovery and trust suffer badly
+
+**Minimum Website Requirements:**
+
+- **Home**: "What MemoryLink is, in one sentence."
+- **Why**: Problems it solves (cross-AI memory, team patterns, code structure)
+- **How**: Architecture diagram, simple workflow
+- **Get Started**: install instructions, quickstart, Hello World
+- **Pricing**: Free / Pro / Enterprise outline
+- **Docs link** (or embed docs)
+
+**Successful tools (Mem0, Supermemory, Cursor, Cody) all:**
+- Show clear "before vs after" stories
+- Have 1–3 **concrete demos** (GIF/video) showing magic in under 60 seconds
+- Make installation feel one-click or one command
+
+**Recommendation:**
+
+- Build a simple website **before public launch**
+- Add a short video or GIF showing:
+  - Logging a learning
+  - Running `get-context` in Cursor/VS Code
+  - Seeing rules + structure + patterns inform AI suggestions
+
+---
+
+## 🧲 QUESTION 6: ADOPTION - Why Tools Succeed or Fail
+
+### Typical Reasons for Abandonment:
+
+1. ❌ First run is confusing; user doesn't see value in 2–3 minutes
+2. ❌ Setup feels heavy (too many steps, configs, or weird errors)
+3. ❌ Tool doesn't fit their main workflow (IDE/AI) well enough
+
+### Typical Reasons for Adoption:
+
+1. ✅ Clear **"aha" moment**: "Oh, now my AI actually knows my project."
+2. ✅ Low friction: one command install, one or two commands to see value
+3. ✅ Appears in their **existing tools** (VS Code/Cursor panel, MCP, CLI)
+
+### For MemoryLink, the Aha Moment Should Be:
+
+**"I solved something once, logged it, and now a different AI (or future me) knows and uses it automatically."**
+
+**Make that path as direct as possible in docs and demos.**
+
+---
+
+## 🧠 QUESTION 7: MAKING MEMORYLINK "SMART"
+
+### A Tool Feels "Smart" When:
+
+- It anticipates what you need
+- It adapts to your context (file, repo, tags)
+- It reduces decision and typing load
+
+### For MemoryLink:
+
+**For Agents:**
+- Provide **structured, prioritized context** (rules → structure → patterns → decisions/learnings)
+- Make calls cheap and predictable (fast `get-context`)
+- Surface code graph and patterns in machine-friendly formats (JSON + clear Markdown)
+
+**For Users:**
+- Make installation: `npm i -g memorylink` or a single binary
+- Make first guide:
+  - `memorylink quickstart`
+  - `memorylink demo`
+  - `memorylink get-context --tag auth`
+- Provide short "recipes":
+  - Solo dev
+  - Team via Git
+  - Cross-AI
+
+### The "Smartest" Feature to Highlight:
+
+> **"MemoryLink lets all your AI tools share one project brain: decisions, code structure, and team best practices – right from your Git repo."**
+
+**That's what nobody else quite does in this combination.**
+
+---
+
+## ✅ CLEAR RECOMMENDATIONS SUMMARY
+
+### 1. Pre-Launch Features
+
+**Ship v1.3 now.**
+- Don't block launch on Tree-sitter or dashboard
+- Do ship MCP + minimal VS Code extension + website
+
+### 2. Integration Strategy
+
+- MCP (done) + VS Code extension pre-launch
+- Other plugins (IntelliJ, deeper ChatGPT/Copilot) after you see adoption patterns
+
+### 3. Business Model
+
+- **Free**: core memory + JS/TS structure + MCP + CLI
+- **Pro**: multi-language structure, patterns, dashboard, analytics
+- **Enterprise**: org features (RBAC, SSO, multi-repo, security)
+
+### 4. Marketing & Adoption
+
+- Build a simple website and at least one short demo before launch
+- Optimize quickstart + "aha" loop over adding more features
+
+---
+
+## 🎯 KEY DIFFERENCES FROM CHATGPT
+
+### Perplexity AI Adds:
+
+1. **VS Code Extension** - Pre-launch requirement (ChatGPT said post-launch)
+   - Perplexity: "Lack of any VS Code integration will hurt more than lack of ChatGPT/Copilot plugins"
+   - ChatGPT: "VS Code extension (thin wrapper only) - post-launch"
+
+2. **Website Requirements** - More detailed than ChatGPT
+   - Perplexity: Specific sections (Home, Why, How, Get Started, Pricing, Docs)
+   - ChatGPT: Minimum (problem, demo GIF, install, agent contract, pricing, docs)
+
+3. **Business Model** - Slightly different Pro pricing
+   - Perplexity: $10–15/user/month
+   - ChatGPT: $15/user/month
+
+### Agreement:
+
+- ✅ Ship v1.3 now
+- ✅ Don't delay for Tree-sitter or dashboard
+- ✅ Website is critical
+- ✅ Free/Pro/Enterprise structure
+- ✅ Focus on "aha" moment
+
+---
+
+**Status**: ✅ Validated and Stored  
+**Priority**: High (adds VS Code extension as pre-launch requirement)  
+**Recommendation**: **Ship v1.3 now with MCP + VS Code extension + website**
+