@joseairosa/recall 1.2.0

package/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install)",
+      "Bash(git mv:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git remote add:*)",
+      "Bash(git push:*)"
+    ],
+    "deny": [],
+    "ask": []
+  },
+  "enabledMcpjsonServers": [
+    "memory"
+  ]
+}

package/.env.example

@@ -0,0 +1,5 @@
+# Redis connection string
+REDIS_URL=redis://localhost:6379
+
+# Anthropic API key for semantic embeddings
+ANTHROPIC_API_KEY=sk-ant-your-api-key-here

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": [
+        "/Users/joseairosa/Development/mcp/mem/dist/index.js"
+      ],
+      "env": {
+        "REDIS_URL": "redis://localhost:6379",
+        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE"
+      }
+    }
+  }
+}

package/.mcp.json.example

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": [
+        "/Users/joseairosa/Development/mcp/mem/dist/index.js"
+      ],
+      "env": {
+        "REDIS_URL": "redis://localhost:6379",
+        "ANTHROPIC_API_KEY": "sk-ant-..."
+      }
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+All notable changes to **Recall** (formerly MCP Memory Server) are 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.2.0] - 2025-10-02
+
+### Added
+- **TTL Support** - Auto-expiring memories with `ttl_seconds` parameter (minimum 60s)
+- **Export/Import Tools** - Backup and restore memories
+  - `export_memories` - Export to JSON with optional filtering by type/importance
+  - `import_memories` - Import from JSON with embedding regeneration option
+- **Duplicate Detection** - Find and merge similar memories
+  - `find_duplicates` - Detect duplicates with similarity threshold (default 0.85)
+  - Auto-merge option with configurable keep strategy
+- **Memory Consolidation** - `consolidate_memories` - Manually merge multiple memories
+- **Analytics Dashboard** - `memory://analytics` resource
+  - Memory trends (24h, 7d, 30d)
+  - Top tags and importance distribution
+  - Activity breakdown by day and type
+- **Cloud Redis Documentation** - Setup guides for Upstash, Redis Cloud, Railway
+
+### Changed
+- Resource URI handling - Fixed pathname parsing for `memory://` scheme
+- Package renamed from `@joseairosa/mcp-memory` to `@joseairosa/recall`
+- Binary command: `mcp-memory` → `recall`
+
+### Technical
+- Added `mergeMemories()` method to MemoryStore
+- Added `ConsolidateMemoriesSchema`, `ExportMemoriesSchema`, `ImportMemoriesSchema`, `FindDuplicatesSchema`
+- Created `src/tools/export-import-tools.ts`
+- Created `src/resources/analytics.ts`
+
+**Tools:** 13 total (6 core + 3 smart context + 4 advanced)
+**Resources:** 9 total
+**Prompts:** 1 (`workspace_context`)
+
+---
+
+## [1.1.0] - 2025-10-02
+
+### Added
+- **Smart Context Management**
+  - `recall_relevant_context` - Proactive memory retrieval based on current task
+  - `analyze_and_remember` - AI-powered conversation analysis and extraction
+  - `summarize_session` - Create session snapshots with summaries
+- **Auto-Injection Prompt**
+  - `workspace_context` - Automatically injects critical directives and decisions at conversation start
+- **Workspace Isolation** - Memories automatically segmented by project directory
+- **AI Analysis** - Claude Haiku integration for intelligent memory extraction
+
+### Changed (Breaking)
+- **API Migration**: OpenAI → Anthropic Claude
+  - Environment variable: `OPENAI_API_KEY` → `ANTHROPIC_API_KEY`
+  - Embeddings: OpenAI 1536-dim → Hybrid (Claude keywords + trigrams) 128-dim
+  - Cost reduction: ~$2/day → ~$0.20/day
+- **Redis Key Structure**: Added workspace prefix `ws:{workspace_id}:`
+- **Package Dependencies**: `openai` → `@anthropic-ai/sdk`
+
+### Technical
+- Added `ConversationAnalyzer` class for AI-powered analysis
+- Created `src/analysis/conversation-analyzer.ts`
+- Created `src/prompts/` directory (index.ts, formatters.ts)
+- Created `src/tools/context-tools.ts`
+- Updated `src/embeddings/generator.ts` - Hybrid embedding approach
+- Added MCP prompts capability to server
+
+**Tools:** 9 total (6 core + 3 smart context)
+**Resources:** 8 total
+**Prompts:** 1 (new capability)
+
+---
+
+## [1.0.0] - 2025-10-02
+
+### Added
+- **Initial Release** - Persistent memory server for Claude using MCP protocol
+- **6 Core Tools**
+  - `store_memory` - Store single memory with metadata
+  - `store_batch_memories` - Batch store multiple memories
+  - `update_memory` - Modify existing memory
+  - `delete_memory` - Remove memory by ID
+  - `search_memories` - Semantic search using embeddings
+  - `organize_session` - Create session snapshots
+- **8 Resources** - Read-only memory access
+  - `memory://recent` - Recent memories (default 50)
+  - `memory://by-type/{type}` - Filter by context type
+  - `memory://by-tag/{tag}` - Filter by tag
+  - `memory://important` - High importance (≥8)
+  - `memory://session/{session_id}` - Session memories
+  - `memory://sessions` - All sessions list
+  - `memory://search?q=query` - Search interface
+  - `memory://summary` - Statistics overview
+- **10 Context Types**
+  - directive, information, heading, decision, code_pattern
+  - requirement, error, todo, insight, preference
+- **Features**
+  - Redis in-memory storage
+  - OpenAI embeddings for semantic search
+  - ULID identifiers
+  - Importance scoring (1-10)
+  - Tag-based organization
+  - Session management
+  - Zod schema validation
+
+### Technical
+- TypeScript with ESM modules
+- Redis (ioredis) for storage
+- OpenAI text-embedding-3-small (1536-dim)
+- MCP SDK v1.0.4
+- Multiple access patterns (hashes, sets, sorted sets)
+
+**Tools:** 6
+**Resources:** 8
+**Prompts:** 0
+
+---
+
+## Migration Guides
+
+### Migrating from v1.1.0 to v1.2.0
+
+**No breaking changes.** All existing functionality works identically.
+
+**New features available immediately:**
+- Set `ttl_seconds` when creating memories
+- Use `export_memories` and `import_memories` tools
+- Access `memory://analytics` resource
+
+**Optional: Upgrade Redis connection**
+- Consider cloud Redis for remote access (Upstash, Redis Cloud, Railway)
+- See README for setup instructions
+
+### Migrating from v1.0.0 to v1.1.0
+
+**Breaking changes - Action required:**
+
+1. **Update environment variable**
+```json
+// Before
+{
+  "env": {
+    "OPENAI_API_KEY": "sk-..."
+  }
+}
+
+// After
+{
+  "env": {
+    "ANTHROPIC_API_KEY": "sk-ant-..."
+  }
+}
+```
+
+2. **Embeddings migration (optional but recommended)**
+```javascript
+// Export without embeddings
+{tool: "export_memories", args: {include_embeddings: false}}
+
+// Import with regenerated embeddings
+{tool: "import_memories", args: {data: "...", regenerate_embeddings: true}}
+```
+
+3. **Workspace awareness**
+- Memories are now isolated by directory
+- Old memories without workspace prefix may need manual migration
+- Use Redis CLI to add `ws:{id}:` prefix if needed
+
+**Benefits:**
+- 10x cost reduction (~$2/day → ~$0.20/day)
+- No OpenAI dependency
+- Faster embedding generation
+- Better context management with smart tools
+
+### Migrating to v1.0.0
+
+Initial release - no migration needed.
+
+---
+
+## Links
+
+- **GitHub**: https://github.com/joseairosa/recall
+- **npm**: https://www.npmjs.com/package/@joseairosa/recall
+- **Issues**: https://github.com/joseairosa/recall/issues

package/CLAUDE.md

@@ -0,0 +1,345 @@
+# CLAUDE.md - MCP Memory Server
+
+Project-specific instructions for Claude when working with this codebase.
+
+---
+
+## Project Context
+
+This is an MCP (Model Context Protocol) server that provides **long-term memory** for Claude conversations. It stores context in Redis with semantic search capabilities to survive context window limitations.
+
+**Key Principle**: This server IS the solution to context loss - treat it with care and always maintain backward compatibility.
+
+---
+
+## Development Guidelines
+
+### Code Style
+
+- **TypeScript**: Strict mode, full type safety
+- **ESM Modules**: Use `.js` extensions in imports (even for `.ts` files)
+- **Naming**: camelCase for variables/functions, PascalCase for types/classes
+- **Files**: kebab-case for filenames (e.g., `memory-store.ts`)
+
+### Architecture Principles
+
+1. **Immutable Memory IDs**: Never change ULID generation - memories must remain accessible
+2. **Backward Compatible**: New context types OK, removing types breaks existing memories
+3. **Index Integrity**: Always update ALL indexes when modifying/deleting memories
+4. **Atomic Operations**: Use Redis pipelines for multi-step updates
+5. **Error Handling**: Use MCP error codes (`ErrorCode.InvalidRequest`, `ErrorCode.InternalError`)
+
+### Redis Data Model
+
+**NEVER** change these key patterns without migration:
+```
+memory:{id}              → Hash
+memories:all             → Set
+memories:timeline        → Sorted Set (score = timestamp)
+memories:type:{type}     → Set
+memories:tag:{tag}       → Set
+memories:important       → Sorted Set (score = importance)
+session:{id}             → Hash
+sessions:all             → Set
+```
+
+### Context Types (Do Not Remove)
+
+These 10 types are core to the system:
+- `directive`, `information`, `heading`, `decision`, `code_pattern`, `requirement`, `error`, `todo`, `insight`, `preference`
+
+**Adding new types**: OK, add to enum in [types.ts](src/types.ts)
+**Removing types**: NO - breaks existing memories
+
+### Importance Scale
+
+- **1-3**: Low (transient)
+- **4-7**: Medium (general)
+- **8-10**: High (critical, auto-indexed)
+
+**Do not change**: The ≥8 threshold for `memories:important` index
+
+---
+
+## Making Changes
+
+### Adding a New Tool
+
+1. Add Zod schema to [types.ts](src/types.ts)
+2. Add method to `MemoryStore` class in [memory-store.ts](src/redis/memory-store.ts)
+3. Add tool handler to [tools/index.ts](src/tools/index.ts)
+4. Update documentation in [README.md](README.md)
+
+### Adding a New Resource
+
+1. Add resource handler to [resources/index.ts](src/resources/index.ts)
+2. Add routing in [index.ts](src/index.ts) `ReadResourceRequestSchema` handler
+3. Add to resource list in `ListResourcesRequestSchema` handler
+4. Update documentation
+
+### Modifying Storage Logic
+
+**CRITICAL**: If changing `MemoryStore` methods:
+1. Ensure index updates are atomic (use pipelines)
+2. Test with existing Redis data
+3. Document migration path if needed
+4. Update version in [package.json](package.json)
+
+### Adding Dependencies
+
+- Keep bundle size small (currently 35KB)
+- Prefer native Node.js APIs when possible
+- Check for ESM compatibility
+- Update [package.json](package.json)
+
+---
+
+## Build & Test
+
+### Build
+```bash
+npm run build      # Production build
+npm run dev        # Watch mode
+```
+
+### Manual Testing
+```bash
+# Start Redis
+redis-server
+
+# Run server (manual test)
+REDIS_URL=redis://localhost:6379 OPENAI_API_KEY=sk-... node dist/index.js
+
+# In another terminal, test Redis
+redis-cli
+> KEYS *
+```
+
+### Verify MCP Config
+```bash
+# Check Claude Desktop config
+cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
+
+# Check logs
+tail -f ~/Library/Logs/Claude/mcp*.log
+```
+
+---
+
+## Common Tasks
+
+### Update OpenAI Model
+
+Edit [embeddings/generator.ts](src/embeddings/generator.ts):
+```typescript
+model: 'text-embedding-3-small',  // Current
+// Change to: 'text-embedding-3-large' for better quality
+```
+
+⚠️ **Warning**: Changing model invalidates existing embeddings! Need migration.
+
+### Add New Context Type
+
+1. Edit [types.ts](src/types.ts):
+```typescript
+export const ContextType = z.enum([
+  // existing...
+  'your_new_type',
+]);
+```
+
+2. Update documentation in [README.md](README.md)
+
+### Increase Embedding Dimensions
+
+If switching to larger embedding model:
+1. Update `embedding` field handling in [memory-store.ts](src/redis/memory-store.ts)
+2. Existing memories will have wrong dimensions - need migration
+3. Consider versioning: `embedding_v1`, `embedding_v2`
+
+---
+
+## Database Migrations
+
+**Current**: No formal migration system
+
+**If Redis Schema Changes**:
+1. Create migration script in `scripts/migrate-{version}.ts`
+2. Document in `MIGRATIONS.md`
+3. Provide rollback instructions
+4. Test on copy of production data first
+
+**Never** delete old keys without migration path!
+
+---
+
+## Performance Considerations
+
+### Semantic Search Bottlenecks
+
+**Current**: O(n) cosine similarity in-app
+- Fine for <10k memories (~2s)
+- Slow for >50k memories
+
+**Future**: Use RediSearch with vector similarity
+- O(log n) with HNSW index
+- Requires Redis Stack
+- Need migration for index creation
+
+### OpenAI API Costs
+
+- `text-embedding-3-small`: ~$0.0001 per 1k tokens
+- Average memory: ~100 tokens = $0.00001
+- 10k memories: ~$0.10
+- Use batch API when storing >5 memories
+
+### Redis Memory Usage
+
+- Per memory: ~2KB (content + embedding + indexes)
+- 10k memories: ~20MB
+- 100k memories: ~200MB
+- Redis can handle this easily in-memory
+
+---
+
+## Security
+
+### Current (Local Use)
+
+- ✅ Runs on localhost
+- ✅ No network exposure
+- ✅ Uses local Redis
+
+### For Production
+
+Would need:
+- [ ] Redis AUTH password
+- [ ] TLS for Redis connection
+- [ ] Rate limiting on tools
+- [ ] User namespacing
+- [ ] API key rotation
+- [ ] Audit logging
+
+---
+
+## Debugging
+
+### Server Not Starting
+
+```bash
+# Check Redis
+redis-cli ping
+
+# Check env vars
+echo $REDIS_URL
+echo $OPENAI_API_KEY
+
+# Check logs
+tail -f ~/Library/Logs/Claude/mcp*.log
+```
+
+### Memory Not Storing
+
+1. Check OpenAI API key validity
+2. Check Redis connection
+3. Look for errors in Claude Desktop logs
+4. Test Redis directly: `redis-cli KEYS memory:*`
+
+### Search Not Working
+
+1. Verify embeddings are generated (check `embedding` field length)
+2. Check OpenAI API quota
+3. Verify cosine similarity calculation
+4. Test with exact content match first
+
+---
+
+## Documentation Updates
+
+When modifying functionality:
+
+1. Update [README.md](README.md) - User-facing docs
+2. Update [QUICKSTART.md](QUICKSTART.md) - If setup changes
+3. Update [ai_docs/learnings/README.md](ai_docs/learnings/README.md) - Technical insights
+4. Update [ai_docs/plans/README.md](ai_docs/plans/README.md) - Architecture changes
+5. Update this file - Development guidelines
+
+---
+
+## Version Management
+
+**Current**: 1.0.0
+
+**Semantic Versioning**:
+- **Major (2.0.0)**: Breaking changes (schema changes, removed tools/resources)
+- **Minor (1.1.0)**: New features (new tools, resources, context types)
+- **Patch (1.0.1)**: Bug fixes, performance improvements
+
+**Before Publishing**:
+- Test with real Redis instance
+- Verify all tools work
+- Check bundle size
+- Update CHANGELOG.md
+
+---
+
+## Don't Break
+
+### Critical Files (Change with Extreme Care)
+
+- [types.ts](src/types.ts) - Schema changes break existing data
+- [memory-store.ts](src/redis/memory-store.ts) - Storage logic changes need migration
+- [package.json](package.json) - Dependency changes affect bundle
+
+### Safe to Modify
+
+- [README.md](README.md) - Documentation only
+- [resources/index.ts](src/resources/index.ts) - Adding resources is safe
+- [tools/index.ts](src/tools/index.ts) - Adding tools is safe
+
+---
+
+## Testing Checklist
+
+Before committing major changes:
+
+- [ ] TypeScript compiles (`npm run build`)
+- [ ] Bundle size reasonable (`ls -lh dist/index.js`)
+- [ ] Shebang present (`head -1 dist/index.js`)
+- [ ] Can store memory
+- [ ] Can retrieve memory
+- [ ] Can search memories
+- [ ] Sessions work
+- [ ] All indexes update correctly
+- [ ] Error handling works
+- [ ] Documentation updated
+
+---
+
+## Emergency Rollback
+
+If production Redis has issues:
+
+```bash
+# Backup Redis
+redis-cli SAVE
+cp /var/lib/redis/dump.rdb dump.rdb.backup
+
+# Restore from backup
+redis-cli SHUTDOWN
+cp dump.rdb.backup /var/lib/redis/dump.rdb
+redis-server
+```
+
+---
+
+## Support
+
+**Maintainer**: José Airosa
+**Issues**: File in GitHub (once published)
+**Logs**: `~/Library/Logs/Claude/`
+
+---
+
+**Last Updated**: 2025-10-02
+**Version**: 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 José Airosa
+
+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.