@contextmirror/claude-memory 0.4.0 → 0.4.2

package/README.md

@@ -4,36 +4,56 @@ Cross-project memory for Claude Code. Give Claude awareness of ALL your projects
 
 ## 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 claude-memory
-claude-memory scan ~/Projects
+npm install -g @contextmirror/claude-memory
+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.
+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 claude-memory
+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": {
@@ -44,60 +64,239 @@ Create `.mcp.json` in your home directory or project:
 }
 ```
 
-### 4. Restart Claude Code
+## What Can You Ask?
+
+Once set up, try asking Claude:
 
-Now Claude has access to your project memory!
+| 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 |
+| `claude-memory scan --check` | Check what's stale without scanning |
 | `claude-memory list` | List known projects |
 | `claude-memory show <project>` | Show project details |
+| `claude-memory briefing [dir]` | Generate CLAUDE.md for a project |
 | `claude-memory init` | Generate CLAUDE.md for current project |
-| `claude-memory generate` | Generate CLAUDE.md for all projects |
+| `claude-memory exclude <project>` | Exclude project from future scans |
+| `claude-memory include <project>` | Re-include an excluded project |
 | `claude-memory mcp` | Start MCP server |
 
+## Staleness Detection
+
+claude-memory tracks when your projects change:
+
+```bash
+claude-memory scan --check
+
+# Output:
+# 🧠 Claude Memory - Staleness Check
+#
+# ⚠️  2 project(s) need updating:
+#   📝 my-project (New commits since last scan)
+#   📄 another-project (Key files modified)
+#
+# Run `claude-memory scan --quick` to refresh only stale projects.
+```
+
+**Detection methods:**
+- **Git activity** - New commits since last scan
+- **File changes** - package.json, CLAUDE.md, etc. modified
+- **Age** - Projects not scanned in 7+ days
+
 ## 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 |
+| `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 |
+
+### Example Interactions
+
+**Ask about all projects:**
+> "What projects do I have?"
+
+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)."
+
+**Get details about a specific project:**
+> "Tell me about the api-server"
+
+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
+## Data Storage
 
-Once set up, you can ask Claude:
+All data stays local on your machine:
 
-- "What other projects do I have?"
-- "Tell me about my CM Remake project"
-- "Generate a CLAUDE.md for this project"
-- "Which of my projects use React?"
+```
+~/.claude-memory/
+├── 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 (1/day)
+└── license.json        # Pro license (if activated)
+```
 
-Claude will query your project memory and respond with real context.
+## Troubleshooting
 
-## Data Storage
+### "No projects found"
 
-All data stays local:
+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
 ```
-~/.claude-memory/
-├── context.json        # Project metadata
-└── global-context.md   # Human-readable overview
+
+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
+
+| Feature | Description |
+|---------|-------------|
+| 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.
 
 ## License
 
@@ -106,3 +305,7 @@ MIT
 ## Author
 
 Nathan (with Claude as co-developer)
+
+---
+
+*Part of the [Context Mirror](https://github.com/contextmirror) project*

package/dist/cli.js

@@ -22,7 +22,7 @@ const program = new Command();
 program
     .name('claude-memory')
     .description('Cross-project memory for Claude Code')
-    .version('0.1.0');
+    .version('0.4.2');
 // Scan command
 program
     .command('scan')
@@ -37,7 +37,10 @@ program
     if (options.check) {
         const context = loadContext();
         if (!context) {
-            console.log('No projects scanned yet. Run: claude-memory scan');
+            console.log('❌ No projects scanned yet.\n');
+            console.log('Get started:');
+            console.log('  claude-memory setup           # Interactive wizard (recommended)');
+            console.log('  claude-memory scan ~/Projects # Scan a specific directory');
             return;
         }
         const report = detectStaleProjects(context);
@@ -119,7 +122,10 @@ program
     .action(() => {
     const context = loadContext();
     if (!context) {
-        console.log('No projects scanned yet. Run: claude-memory scan');
+        console.log('❌ No projects scanned yet.\n');
+        console.log('Get started:');
+        console.log('  claude-memory setup           # Interactive wizard (recommended)');
+        console.log('  claude-memory scan ~/Projects # Scan a specific directory');
         return;
     }
     console.log('🧠 Known Projects\n');
@@ -139,14 +145,27 @@ program
     .action((projectName) => {
     const context = loadContext();
     if (!context) {
-        console.log('No projects scanned yet. Run: claude-memory scan');
+        console.log('❌ No projects scanned yet.\n');
+        console.log('Get started:');
+        console.log('  claude-memory setup           # Interactive wizard (recommended)');
+        console.log('  claude-memory scan ~/Projects # Scan a specific directory');
         return;
     }
     const project = context.projects.find((p) => p.name.toLowerCase() === projectName.toLowerCase() || p.path.includes(projectName));
     if (!project) {
-        console.log(`Project not found: ${projectName}`);
-        console.log('\nKnown projects:');
-        context.projects.forEach((p) => console.log(`  - ${p.name}`));
+        console.log(`❌ Project not found: "${projectName}"\n`);
+        console.log('Did you mean one of these?\n');
+        // Show projects sorted by similarity to the query
+        const lowerQuery = projectName.toLowerCase();
+        const sorted = [...context.projects].sort((a, b) => {
+            const aScore = a.name.toLowerCase().includes(lowerQuery) ? 1 : 0;
+            const bScore = b.name.toLowerCase().includes(lowerQuery) ? 1 : 0;
+            return bScore - aScore;
+        });
+        sorted.slice(0, 5).forEach((p) => console.log(`  ${p.name}  (${p.path})`));
+        if (context.projects.length > 5) {
+            console.log(`\n  ... and ${context.projects.length - 5} more. Run 'claude-memory list' to see all.`);
+        }
         return;
     }
     console.log(`\n📁 ${project.name}\n`);
@@ -168,7 +187,10 @@ program
     .action((projectQuery) => {
     const context = loadContext();
     if (!context) {
-        console.log('No projects scanned yet. Run: claude-memory scan');
+        console.log('❌ No projects scanned yet.\n');
+        console.log('Get started:');
+        console.log('  claude-memory setup           # Interactive wizard (recommended)');
+        console.log('  claude-memory scan ~/Projects # Scan a specific directory');
         return;
     }
     // Find the project
@@ -181,7 +203,8 @@ program
             console.log('   This project will be skipped in future scans.');
             return;
         }
-        console.log(`Project not found: ${projectQuery}`);
+        console.log(`❌ Project not found: "${projectQuery}"\n`);
+        console.log('Tip: Use the project name or path. Run "claude-memory list" to see all projects.');
         return;
     }
     addExclusion(project.path);
@@ -198,16 +221,23 @@ program
     .action((projectQuery) => {
     const context = loadContext();
     if (!context) {
-        console.log('No projects scanned yet. Run: claude-memory scan');
+        console.log('❌ No projects scanned yet.\n');
+        console.log('Get started:');
+        console.log('  claude-memory setup           # Interactive wizard (recommended)');
+        console.log('  claude-memory scan ~/Projects # Scan a specific directory');
         return;
     }
     const excluded = context.excludedProjects || [];
     const match = excluded.find(p => p.toLowerCase().includes(projectQuery.toLowerCase()));
     if (!match) {
-        console.log(`Project not in exclusion list: ${projectQuery}`);
+        console.log(`❌ Project not in exclusion list: "${projectQuery}"\n`);
         if (excluded.length > 0) {
-            console.log('\nCurrently excluded:');
-            excluded.forEach(p => console.log(`  - ${p}`));
+            console.log('Currently excluded:');
+            excluded.forEach(p => console.log(`  ${p}`));
+            console.log('\nRun "claude-memory excluded" to see all excluded projects.');
+        }
+        else {
+            console.log('No projects are currently excluded.');
         }
         return;
     }

package/landing/index.html

@@ -739,7 +739,7 @@
           <div class="price">$8 <span>/month</span></div>
           <ul>
             <li>Everything in Free</li>
-            <li class="coming">Team memory sync</li>
+            <li>Cross-project code search</li>
             <li class="coming">Semantic search</li>
             <li class="coming">Custom CLAUDE.md templates</li>
             <li class="coming">Priority support</li>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextmirror/claude-memory",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Cross-project memory for Claude Code - know about all your projects",
   "type": "module",
   "main": "dist/cli.js",
@@ -19,10 +19,18 @@
   },
   "keywords": [
     "claude",
+    "claude-code",
     "mcp",
+    "model-context-protocol",
     "memory",
     "context",
-    "ai"
+    "ai",
+    "llm",
+    "anthropic",
+    "cross-project",
+    "developer-tools",
+    "productivity",
+    "code-assistant"
   ],
   "author": "Nathan",
   "license": "MIT",