@contextmirror/claude-memory 0.4.1 → 0.4.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nathan / Context Mirror
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,48 +1,64 @@
 # claude-memory
 
+[![npm version](https://img.shields.io/npm/v/@contextmirror/claude-memory.svg)](https://www.npmjs.com/package/@contextmirror/claude-memory)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Discord](https://img.shields.io/discord/1454173469242822669?color=5865F2&label=Discord&logo=discord&logoColor=white)](https://discord.gg/JBpsSFB7EQ)
+
 Cross-project memory for Claude Code. Give Claude awareness of ALL your projects, not just the one you're in.
 
 ## The Problem
 
-Every Claude Code session starts fresh. Switch to a different project folder and Claude has no idea about your other work. You end up re-explaining your codebase, your patterns, your other projects.
+Every Claude Code session starts fresh. Switch to a different project folder and Claude has no idea about your other work. You end up re-explaining your codebase, your patterns, your architecture.
+
+**Without claude-memory:**
+- "I have an API server in another folder that uses the same auth pattern..."
+- "My component library has a Button I want to reuse..."
+- "How did I handle this in my other project again?"
+
+Claude doesn't know. It can't see outside the current directory.
 
 ## The Solution
 
 ```bash
 npm install -g @contextmirror/claude-memory
-claude-memory scan ~/Projects
+claude-memory setup
 ```
 
-Now Claude knows about all your projects. Ask "What other projects do I have?" or "Generate a CLAUDE.md for this project" and Claude just knows.
-
-## Features
-
-- **Cross-project awareness** - Claude knows about all your projects
-- **Staleness detection** - Automatically detects when projects need rescanning
-- **Quick scans** - Only rescan projects that have changed
-- **Update notifications** - Get notified when new versions are available
-- **CLAUDE.md generation** - Auto-generate project documentation
-- **MCP integration** - Works seamlessly with Claude Code
+Now Claude knows about all your projects. Ask "What other projects do I have?" or "How do I handle auth in my API?" and Claude just knows.
 
 ## Quick Start
 
-### 1. Install
+### 1. Install globally
 
 ```bash
 npm install -g @contextmirror/claude-memory
 ```
 
-### 2. Scan your projects
+### 2. Run the setup wizard
 
 ```bash
-claude-memory scan ~/Projects  # or wherever your code lives
+claude-memory setup
 ```
 
-### 3. Add MCP to Claude Code
+This will:
+- Scan your projects directory
+- Configure MCP for Claude Code
+- Optionally generate CLAUDE.md files
 
-Create `.mcp.json` in your home directory or project:
+### 3. Restart Claude Code
 
-```json
+That's it. Claude now has access to your project memory.
+
+---
+
+**Alternative: Manual setup**
+
+```bash
+# Scan your projects
+claude-memory scan ~/Projects
+
+# Add MCP to Claude Code (create ~/.mcp.json)
 {
   "mcpServers": {
     "claude-memory": {
@@ -53,16 +69,37 @@ Create `.mcp.json` in your home directory or project:
 }
 ```
 
-### 4. Restart Claude Code
+## What Can You Ask?
 
-Now Claude has access to your project memory!
+Once set up, try asking Claude:
+
+| Question | What Claude Does |
+|----------|------------------|
+| "What projects do I have?" | Lists all your projects with tech stacks |
+| "Tell me about my API server" | Shows project details, branch, recent activity |
+| "Which projects use React?" | Searches across all projects |
+| "Generate a CLAUDE.md for this project" | Creates context documentation |
+| "Is my project data up to date?" | Checks for stale data |
+| "How do I handle auth in my other projects?" | Cross-project pattern lookup |
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Cross-project awareness** | Claude knows about all your projects |
+| **Staleness detection** | Automatically detects when projects need rescanning |
+| **Quick scans** | Only rescan projects that have changed |
+| **Update notifications** | Get notified when new versions are available |
+| **CLAUDE.md generation** | Auto-generate project documentation |
+| **MCP integration** | Works seamlessly with Claude Code |
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
+| `claude-memory setup` | Interactive setup wizard (recommended) |
 | `claude-memory scan [dir]` | Scan directory for projects |
-| `claude-memory scan --quick` | Only rescan stale projects (faster) |
+| `claude-memory scan --quick` | Only rescan stale projects |
 | `claude-memory scan --check` | Check what's stale without scanning |
 | `claude-memory list` | List known projects |
 | `claude-memory show <project>` | Show project details |
@@ -71,14 +108,12 @@ Now Claude has access to your project memory!
 | `claude-memory exclude <project>` | Exclude project from future scans |
 | `claude-memory include <project>` | Re-include an excluded project |
 | `claude-memory mcp` | Start MCP server |
-| `claude-memory setup` | Interactive setup wizard |
 
 ## Staleness Detection
 
-claude-memory automatically detects when your projects need rescanning:
+claude-memory tracks when your projects change:
 
 ```bash
-# Check what's stale
 claude-memory scan --check
 
 # Output:
@@ -86,7 +121,7 @@ claude-memory scan --check
 #
 # ⚠️  2 project(s) need updating:
 #   📝 my-project (New commits since last scan)
-#   📄 another-project (Key files modified since last scan)
+#   📄 another-project (Key files modified)
 #
 # Run `claude-memory scan --quick` to refresh only stale projects.
 ```
@@ -98,64 +133,139 @@ claude-memory scan --check
 
 ## MCP Tools
 
-When connected, Claude Code gets these tools:
+When connected, Claude Code gets access to these tools:
 
 | Tool | Purpose |
 |------|---------|
-| `get_global_context` | Overview of all your projects + staleness info |
+| `get_global_context` | Overview of all projects + staleness info |
 | `get_project_summary` | Details about a specific project |
 | `get_project_analysis` | Deep analysis for CLAUDE.md generation |
 | `search_projects` | Search across all projects |
 | `record_insight` | Save cross-project patterns |
 | `search_code` | **[Pro]** Search code across all projects |
 
-## Update Notifications
+### Example Interactions
 
-claude-memory checks for updates automatically (once per day, cached). When a new version is available, Claude will see:
+**Ask about all projects:**
+> "What projects do I have?"
 
-```
-⬆️ Update available: v0.3.0 → v0.4.0
+Claude uses `get_global_context` and responds:
+> "You have 5 projects: dashboard-app (React/Next.js), api-server (Node/Express), component-library (React/Storybook), cli-tool (TypeScript), and landing-site (Vite)."
 
-Run to update:
-npm update -g @contextmirror/claude-memory
+**Get details about a specific project:**
+> "Tell me about the api-server"
 
-After updating, restart Claude Code to use the new version.
-```
+Claude uses `get_project_summary` and responds:
+> "api-server is a Node.js/Express API with JWT authentication. It's on the `feature/auth` branch with uncommitted changes. Last activity was 2 days ago."
+
+**Search across projects:**
+> "Which of my projects use Tailwind?"
+
+Claude uses `search_projects` and responds:
+> "2 projects use Tailwind CSS: dashboard-app and landing-site."
+
+**Generate documentation:**
+> "Create a CLAUDE.md for this project"
+
+Claude uses `get_project_analysis` to gather deep context, then writes a comprehensive CLAUDE.md file.
 
 ## How It Works
 
-1. **Scan** - Finds projects by looking for package.json, Cargo.toml, pyproject.toml, .git
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   Project A     │     │  Claude Memory  │     │   Claude Code   │
+│   (React App)   │────>│   MCP Server    │<────│                 │
+├─────────────────┤     │                 │     │  "What projects │
+│   Project B     │────>│  ~/.claude-     │     │   use React?"   │
+│   (API Server)  │     │  memory/        │     │                 │
+├─────────────────┤     │  context.json   │     └─────────────────┘
+│   Project C     │────>│                 │
+│   (CLI Tool)    │     └─────────────────┘
+└─────────────────┘
+```
+
+1. **Scan** - Finds projects by looking for package.json, Cargo.toml, pyproject.toml, go.mod, .git
 2. **Extract** - Pulls name, description, tech stack, git info, CLAUDE.md content
 3. **Store** - Saves to `~/.claude-memory/context.json`
 4. **Serve** - MCP server exposes context to Claude Code
 5. **Detect** - Monitors for staleness on each session start
 
-## Example Usage
-
-Once set up, you can ask Claude:
-
-- "What other projects do I have?"
-- "Tell me about my project X"
-- "Generate a CLAUDE.md for this project"
-- "Which of my projects use React?"
-- "Is my project data up to date?"
-
-Claude will query your project memory and respond with real context.
-
 ## Data Storage
 
-All data stays local:
+All data stays local on your machine:
 
 ```
 ~/.claude-memory/
-├── context.json        # Project metadata
-├── context.json.bak    # Backup
+├── context.json        # Project metadata (machine-readable)
+├── context.json.bak    # Automatic backup
 ├── global-context.md   # Human-readable overview
 ├── config.json         # User configuration
-├── update-check.json   # Update check cache
+├── update-check.json   # Update check cache (1/day)
 └── license.json        # Pro license (if activated)
 ```
 
+## Troubleshooting
+
+### "No projects found"
+
+Make sure you're pointing to the right directory:
+```bash
+# Check what directory you're scanning
+claude-memory scan ~/Projects --check
+
+# Common locations to try:
+claude-memory scan ~/Code
+claude-memory scan ~/dev
+claude-memory scan ~/projects
+```
+
+Projects are detected by these files: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, or `.git`
+
+### "MCP tools not showing up in Claude Code"
+
+1. Make sure `.mcp.json` exists in your home directory or project
+2. Restart Claude Code completely (not just the conversation)
+3. Check the MCP config is valid JSON:
+```json
+{
+  "mcpServers": {
+    "claude-memory": {
+      "command": "claude-memory",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### "Data seems outdated"
+
+Run a quick scan to refresh stale projects:
+```bash
+claude-memory scan --quick
+```
+
+Or do a full rescan:
+```bash
+claude-memory scan ~/Projects
+```
+
+### "Git operations are slow"
+
+If you have large repos, git operations may timeout (10s limit). This is normal - the project will still be scanned, just without git info.
+
+### "Want to exclude a project"
+
+```bash
+# Exclude a project from future scans
+claude-memory exclude my-secret-project
+
+# See what's excluded
+claude-memory excluded
+
+# Re-include it later
+claude-memory include my-secret-project
+```
+
 ## Pro Features
 
 Activate with `claude-memory activate <key>`. Get a license at https://claude-memory.dev
@@ -165,6 +275,40 @@ Activate with `claude-memory activate <key>`. Get a license at https://claude-me
 | Cross-project code search | Search code patterns across all your projects |
 | Semantic search | Search by meaning, not just keywords (coming soon) |
 
+## Update Notifications
+
+claude-memory checks for updates automatically (once per day). When a new version is available:
+
+```
+⬆️ Update available: v0.4.0 → v0.5.0
+
+Run to update:
+npm update -g @contextmirror/claude-memory
+```
+
+## FAQ
+
+**Does this use Claude API tokens?**
+No. claude-memory only stores metadata locally. It uses MCP to expose that data to Claude Code - no additional API calls.
+
+**Does it work with Claude Pro/Team?**
+Yes. It works with any Claude Code subscription.
+
+**What languages are supported?**
+Any language. Tech stack detection works best for: JavaScript/TypeScript, Python, Rust, Go. Others show as "other" but still work.
+
+**How often should I rescan?**
+Run `claude-memory scan --quick` when you've made changes to multiple projects. The `--quick` flag only rescans stale projects.
+
+**Is my code uploaded anywhere?**
+No. All data stays in `~/.claude-memory/` on your machine. Nothing is sent to any server.
+
+## Community
+
+Join our Discord for feedback, feature requests, and support:
+
+[![Discord](https://img.shields.io/discord/1454173469242822669?color=5865F2&label=Discord&logo=discord&logoColor=white)](https://discord.gg/JBpsSFB7EQ)
+
 ## License
 
 MIT

package/dist/__tests__/codeSearch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/codeSearch.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { formatSearchResults } from '../utils/codeSearch.js';
+describe('Code Search', () => {
+    describe('formatSearchResults', () => {
+        it('should format empty results correctly', () => {
+            const result = formatSearchResults([], 'test');
+            expect(result).toBe('No results found for "test".');
+        });
+        it('should format single result correctly', () => {
+            const results = [{
+                    project: 'my-project',
+                    projectPath: '/home/user/my-project',
+                    file: '/home/user/my-project/src/index.ts',
+                    relativePath: 'src/index.ts',
+                    line: 10,
+                    content: 'const test = "hello";',
+                    context: {
+                        before: 'import { something } from "./lib";',
+                        after: 'export default test;',
+                    },
+                }];
+            const result = formatSearchResults(results, 'test');
+            expect(result).toContain('# Code Search Results for "test"');
+            expect(result).toContain('Found 1 result');
+            expect(result).toContain('## my-project');
+            expect(result).toContain('src/index.ts:10');
+            expect(result).toContain('const test = "hello";');
+        });
+        it('should group results by project', () => {
+            const results = [
+                {
+                    project: 'project-a',
+                    projectPath: '/path/a',
+                    file: '/path/a/file1.ts',
+                    relativePath: 'file1.ts',
+                    line: 1,
+                    content: 'line 1',
+                    context: { before: '', after: '' },
+                },
+                {
+                    project: 'project-b',
+                    projectPath: '/path/b',
+                    file: '/path/b/file2.ts',
+                    relativePath: 'file2.ts',
+                    line: 2,
+                    content: 'line 2',
+                    context: { before: '', after: '' },
+                },
+                {
+                    project: 'project-a',
+                    projectPath: '/path/a',
+                    file: '/path/a/file3.ts',
+                    relativePath: 'file3.ts',
+                    line: 3,
+                    content: 'line 3',
+                    context: { before: '', after: '' },
+                },
+            ];
+            const result = formatSearchResults(results, 'query');
+            expect(result).toContain('Found 3 results');
+            expect(result).toContain('## project-a');
+            expect(result).toContain('## project-b');
+        });
+    });
+});

package/dist/__tests__/license.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/license.test.js

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { validateKeyFormat, isLemonSqueezyKey } from '../license/index.js';
+describe('License Key Validation', () => {
+    describe('validateKeyFormat', () => {
+        it('should accept valid LemonSqueezy UUID keys', () => {
+            expect(validateKeyFormat('A1B2C3D4-E5F6-7890-ABCD-EF1234567890')).toBe(true);
+            expect(validateKeyFormat('a1b2c3d4-e5f6-7890-abcd-ef1234567890')).toBe(true);
+        });
+        it('should accept valid legacy CM- keys', () => {
+            expect(validateKeyFormat('CM-ABCD-1234-WXYZ')).toBe(true);
+            expect(validateKeyFormat('cm-abcd-1234-wxyz')).toBe(true);
+        });
+        it('should reject invalid key formats', () => {
+            expect(validateKeyFormat('')).toBe(false);
+            expect(validateKeyFormat('invalid-key')).toBe(false);
+            expect(validateKeyFormat('CM-ABC-1234-WXYZ')).toBe(false); // Wrong segment length
+            expect(validateKeyFormat('12345678-1234-1234-1234-123456789')).toBe(false); // Too short
+        });
+    });
+    describe('isLemonSqueezyKey', () => {
+        it('should identify LemonSqueezy UUID keys', () => {
+            expect(isLemonSqueezyKey('A1B2C3D4-E5F6-7890-ABCD-EF1234567890')).toBe(true);
+        });
+        it('should not identify legacy keys as LemonSqueezy', () => {
+            expect(isLemonSqueezyKey('CM-ABCD-1234-WXYZ')).toBe(false);
+        });
+    });
+});

package/dist/__tests__/stalenessDetector.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/stalenessDetector.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { detectStaleProjects } from '../scanner/stalenessDetector.js';
+function createMockProject(overrides = {}) {
+    return {
+        name: 'test-project',
+        path: '/home/user/projects/test-project',
+        description: 'A test project',
+        language: 'typescript',
+        techStack: ['Node.js', 'TypeScript'],
+        currentBranch: 'main',
+        isDirty: false,
+        lastActivity: new Date().toISOString(),
+        hasFiles: {
+            readme: true,
+            claudeMd: false,
+            packageJson: true,
+            gitignore: true,
+        },
+        insights: [],
+        lastScanned: new Date().toISOString(),
+        ...overrides,
+    };
+}
+function createMockContext(projects = [], hoursAgo = 0) {
+    const lastUpdated = new Date(Date.now() - hoursAgo * 60 * 60 * 1000).toISOString();
+    return {
+        schemaVersion: 1,
+        lastUpdated,
+        projects,
+        insights: [],
+        userPatterns: [],
+    };
+}
+describe('Staleness Detection', () => {
+    describe('detectStaleProjects', () => {
+        it('should return no stale projects for fresh data', () => {
+            const context = createMockContext([createMockProject()], 0);
+            const report = detectStaleProjects(context);
+            expect(report.staleProjects).toHaveLength(0);
+            expect(report.dataAgeHours).toBeLessThan(1);
+        });
+        it('should mark data as stale after 24 hours', () => {
+            const context = createMockContext([createMockProject()], 25);
+            const report = detectStaleProjects(context);
+            expect(report.dataAgeHours).toBeGreaterThan(24);
+        });
+        it('should detect projects scanned more than 7 days ago', () => {
+            const oldScanDate = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000).toISOString();
+            const project = createMockProject({ lastScanned: oldScanDate });
+            const context = createMockContext([project], 0);
+            const report = detectStaleProjects(context);
+            expect(report.staleProjects.length).toBeGreaterThanOrEqual(0);
+        });
+        it('should handle empty projects list', () => {
+            const context = createMockContext([], 0);
+            const report = detectStaleProjects(context);
+            expect(report.staleProjects).toHaveLength(0);
+        });
+    });
+});

package/dist/__tests__/updateChecker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/updateChecker.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+// Test version comparison logic
+function isNewerVersion(current, latest) {
+    const currentParts = current.split('.').map(Number);
+    const latestParts = latest.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const curr = currentParts[i] || 0;
+        const lat = latestParts[i] || 0;
+        if (lat > curr)
+            return true;
+        if (lat < curr)
+            return false;
+    }
+    return false;
+}
+describe('Update Checker', () => {
+    describe('version comparison', () => {
+        it('should detect newer major versions', () => {
+            expect(isNewerVersion('0.4.2', '1.0.0')).toBe(true);
+            expect(isNewerVersion('1.0.0', '2.0.0')).toBe(true);
+        });
+        it('should detect newer minor versions', () => {
+            expect(isNewerVersion('0.4.2', '0.5.0')).toBe(true);
+            expect(isNewerVersion('0.4.2', '0.5.1')).toBe(true);
+        });
+        it('should detect newer patch versions', () => {
+            expect(isNewerVersion('0.4.2', '0.4.3')).toBe(true);
+            expect(isNewerVersion('0.4.2', '0.4.10')).toBe(true);
+        });
+        it('should return false for same version', () => {
+            expect(isNewerVersion('0.4.2', '0.4.2')).toBe(false);
+        });
+        it('should return false for older versions', () => {
+            expect(isNewerVersion('0.4.2', '0.4.1')).toBe(false);
+            expect(isNewerVersion('0.4.2', '0.3.9')).toBe(false);
+            expect(isNewerVersion('1.0.0', '0.9.9')).toBe(false);
+        });
+        it('should handle missing patch version', () => {
+            expect(isNewerVersion('0.4', '0.4.1')).toBe(true);
+            expect(isNewerVersion('0.4.1', '0.5')).toBe(true);
+        });
+    });
+});