claude-recall 0.2.0

package/docs/MCP_USER_GUIDE.md

@@ -0,0 +1,115 @@
+# Claude Recall MCP Server User Guide
+
+## Installation
+
+### Global Installation (Recommended)
+```bash
+npm install -g claude-recall
+```
+
+### Local Installation
+```bash
+npm install claude-recall
+```
+
+## Adding to Claude Code
+
+```bash
+# For global installation
+claude mcp add claude-recall claude-recall mcp start
+
+# For local installation
+claude mcp add claude-recall npx claude-recall mcp start
+```
+
+## Available Tools
+
+### 1. Store Memory
+**Tool**: `mcp__claude-recall__store_memory`
+**Purpose**: Save important information for future recall
+
+Example:
+```
+Store this memory: The user prefers TypeScript over JavaScript for all new projects
+```
+
+### 2. Search Memories
+**Tool**: `mcp__claude-recall__search`
+**Purpose**: Find previously stored information
+
+Example:
+```
+Search my memories for: TypeScript preferences
+```
+
+### 3. Retrieve Memory
+**Tool**: `mcp__claude-recall__retrieve_memory`
+**Purpose**: Get specific memories by ID or recent memories
+
+Example:
+```
+Retrieve my recent memories about coding preferences
+```
+
+### 4. Get Statistics
+**Tool**: `mcp__claude-recall__get_stats`
+**Purpose**: View memory usage statistics
+
+Example:
+```
+Show me my Claude Recall statistics
+```
+
+### 5. Clear Context
+**Tool**: `mcp__claude-recall__clear_context`
+**Purpose**: Clear session-specific context
+
+Example:
+```
+Clear my current Claude Recall context (confirm: true)
+```
+
+## Memory Persistence
+
+- Memories are stored in a local SQLite database
+- Sessions persist across Claude Code restarts
+- Database location: `~/.claude-recall/claude-recall.db`
+- Session data: `~/.claude-recall/sessions.json`
+
+## Troubleshooting
+
+### MCP Server Not Starting
+1. Check Claude Code logs: `~/.claude-code/logs/`
+2. Test manually: `claude-recall mcp start`
+3. Verify installation: `which claude-recall`
+
+### Memories Not Persisting
+1. Check database permissions: `ls -la ~/.claude-recall/`
+2. Verify disk space: `df -h`
+3. Check logs for errors
+
+### Rate Limiting
+- Default: 100 requests per minute per session
+- If rate limited, wait 60 seconds
+- Check current usage with health endpoint
+
+## Advanced Configuration
+
+### Environment Variables
+- `CLAUDE_RECALL_DB_PATH`: Custom database location
+- `CLAUDE_RECALL_LOG_LEVEL`: Set to 'debug' for verbose logging
+- `CLAUDE_RECALL_RATE_LIMIT`: Custom rate limit (default: 100)
+
+### Debug Mode
+```bash
+# Run with debug logging
+NODE_ENV=development DEBUG=claude-recall:* claude-recall mcp start
+```
+
+## Migration from File Watcher
+
+If you were using the old file watcher version:
+1. Export your memories: `claude-recall export`
+2. Install new version: `npm install -g claude-recall@latest`
+3. Add MCP server: `claude mcp add claude-recall claude-recall mcp start`
+4. Import memories: `claude-recall import memories.json`

package/docs/release-process.md

@@ -0,0 +1,86 @@
+# Release Process for Claude Recall
+
+## Overview
+This document outlines the process for creating public releases from the private development repository.
+
+## Repository Structure
+- **Private**: `claude-recall-dev` - All development work
+- **Public**: `claude-recall` - Clean, public releases only
+
+## Release Steps
+
+### 1. Prepare Release Branch
+```bash
+# From main branch with all features ready
+git checkout main
+git checkout -b release/vX.Y.Z
+```
+
+### 2. Clean Development Files
+The following are automatically excluded by .gitignore-dev:
+- `test-*.{ts,js,sh,md}` files
+- `demo-*.ts` and `debug-*.ts` files
+- Log files and test artifacts
+- Test directories (test-final/, tests-arlo/, etc.)
+
+Additional manual cleanup:
+- Remove internal documentation (STAGE*.md, task-phase-*.md)
+- Remove swarm-tasks/ directory
+- Remove .claude-flow/ directory
+- Remove settings/ and config/ directories
+- Remove any .example.json files
+
+### 3. Update Public Files
+```bash
+# Copy public versions (keep these in a /public folder on main)
+cp public/README-public.md README.md
+cp public/.gitignore-public .gitignore
+cp public/LICENSE LICENSE
+```
+
+### 4. Update Version
+```bash
+# Update package.json version
+npm version patch/minor/major
+```
+
+### 5. Build and Test
+```bash
+npm run build
+npm test
+```
+
+### 6. Commit Clean Version
+```bash
+git add -A
+git commit -m "Release vX.Y.Z"
+git tag vX.Y.Z
+```
+
+### 7. Push to Public Repository
+```bash
+# Add public remote if not already added
+git remote add public https://github.com/raoulbia-ai/claude-recall.git
+
+# Push release branch to public main
+git push public release/vX.Y.Z:main --force
+git push public vX.Y.Z  # Push tag
+```
+
+### 8. Create GitHub Release
+1. Go to https://github.com/raoulbia-ai/claude-recall/releases
+2. Click "Create a new release"
+3. Select the version tag
+4. Add release notes
+5. Publish release
+
+### 9. Publish to NPM (optional)
+```bash
+npm publish
+```
+
+## Important Notes
+- NEVER push development branches to public repo
+- Always test the clean build before pushing
+- Keep public README focused on users, not developers
+- Maintain version consistency across package.json and git tags

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "claude-recall",
+  "version": "0.2.0",
+  "description": "MCP server for persistent memory in Claude Code conversations",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-recall": "dist/cli/claude-recall-cli.js"
+  },
+  "files": [
+    "dist/",
+    "scripts/postinstall.js",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js || true",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "build": "tsc && mkdir -p dist/memory && cp src/memory/schema.sql dist/memory/ && chmod +x dist/cli/claude-recall-cli.js",
+    "build:cli": "tsc && chmod +x dist/cli/claude-recall-cli.js",
+    "dev": "ts-node",
+    "start": "ts-node src/server.ts",
+    "start:dev": "nodemon --exec ts-node src/server.ts",
+    "claude-recall": "ts-node src/cli/claude-recall-cli.ts",
+    "install:global": "npm run build && npm link",
+    "stats": "npm run claude-recall stats",
+    "search": "npm run claude-recall search",
+    "migrate:service-layer": "ts-node migrate-to-service-layer.ts",
+    "rollback:service-layer": "ts-node -e \"require('./migrate-to-service-layer').ServiceLayerMigration.rollback()\"",
+    "preuninstall": "node scripts/uninstall.js",
+    "prepare": "npm run build",
+    "mcp:start": "node dist/cli/claude-recall-cli.js mcp start",
+    "mcp:dev": "ts-node src/cli/claude-recall-cli.ts mcp start",
+    "mcp:debug": "NODE_ENV=development DEBUG=claude-recall:* ts-node src/cli/claude-recall-cli.ts mcp start",
+    "mcp:test": "echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}' | npm run mcp:start",
+    "mcp:health": "echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"health/check\",\"params\":{}}' | npm run mcp:start"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "memory",
+    "ai",
+    "claude",
+    "anthropic",
+    "model-context-protocol"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "Claude Recall Team",
+  "license": "ISC",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raoulbia-ai/claude-recall.git"
+  },
+  "homepage": "https://github.com/raoulbia-ai/claude-recall#readme",
+  "bugs": {
+    "url": "https://github.com/raoulbia-ai/claude-recall/issues"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.1.0",
+    "jest": "^30.0.5",
+    "ts-jest": "^29.4.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@types/bcrypt": "^6.0.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.3",
+    "@types/jsonwebtoken": "^9.0.10",
+    "bcrypt": "^6.0.0",
+    "better-sqlite3": "^12.2.0",
+    "chalk": "^5.5.0",
+    "commander": "^12.1.0",
+    "express": "^5.1.0",
+    "jsonwebtoken": "^9.0.2"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+console.log('\n🚀 Setting up Claude Recall MCP server...\n');
+
+// Find ~/.claude.json
+const claudeConfigPath = path.join(os.homedir(), '.claude.json');
+
+// Check if file exists
+if (!fs.existsSync(claudeConfigPath)) {
+  console.log('❌ Could not find ~/.claude.json');
+  console.log('   Please make sure Claude Code is installed and has been run at least once.');
+  console.log('   Then run: npm install -g claude-recall');
+  process.exit(0);
+}
+
+try {
+  // Read current config
+  const configContent = fs.readFileSync(claudeConfigPath, 'utf8');
+  const config = JSON.parse(configContent);
+
+  // Ensure mcpServers exists
+  if (!config.mcpServers) {
+    config.mcpServers = {};
+  }
+
+  // Check if claude-recall already exists
+  if (config.mcpServers['claude-recall']) {
+    console.log('⚠️  Claude Recall is already configured in ~/.claude.json');
+    console.log('   Updating configuration...');
+  }
+
+  // Set up database location in user's home directory
+  const dbDir = path.join(os.homedir(), '.claude-recall');
+  
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(dbDir)) {
+    fs.mkdirSync(dbDir, { recursive: true });
+    console.log(`📁 Created database directory: ${dbDir}`);
+  }
+
+  // Add or update claude-recall configuration
+  config.mcpServers['claude-recall'] = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['claude-recall', 'mcp', 'start'],
+    env: {
+      CLAUDE_RECALL_DB_PATH: dbDir,
+      CLAUDE_RECALL_DB_NAME: 'claude-recall.db'
+    }
+  };
+
+  // Write back the config with proper formatting
+  fs.writeFileSync(claudeConfigPath, JSON.stringify(config, null, 2));
+
+  console.log('✅ Successfully configured Claude Recall in ~/.claude.json');
+  console.log('\n📝 Next steps:');
+  console.log('   1. Restart Claude Code if it\'s currently running');
+  console.log('   2. Claude Recall will start automatically when you launch Claude Code');
+  console.log('\n🎉 Installation complete!\n');
+
+} catch (error) {
+  console.error('❌ Error updating ~/.claude.json:', error.message);
+  console.log('\nPlease manually add Claude Recall to your ~/.claude.json file:');
+  console.log(JSON.stringify({
+    "claude-recall": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["claude-recall", "mcp", "start"],
+      "env": {}
+    }
+  }, null, 2));
+}