@joseairosa/recall 1.6.0 → 1.7.0

package/.claude/agents/REGISTRY.md

@@ -0,0 +1,182 @@
+# Agent Registry - Recall MCP Server
+
+This registry defines specialized agents for the Recall project. The Coordinator should route tasks to appropriate agents based on their specialization.
+
+---
+
+## Available Agents
+
+### 1. Code Agent (`code`)
+
+**Specialization**: TypeScript implementation, MCP tools, Redis operations
+
+**Use When**:
+- Implementing new tools or resources
+- Modifying memory-store.ts logic
+- Adding new context types or schemas
+- Fixing bugs in core functionality
+
+**Key Files**:
+- `src/types.ts` - Schemas
+- `src/redis/memory-store.ts` - Storage
+- `src/tools/*.ts` - Tool implementations
+- `src/index.ts` - Request routing
+
+**Guidelines**:
+- Always use Zod schemas for validation
+- Use Redis pipelines for atomic operations
+- Maintain backward compatibility
+- Add comprehensive error handling
+
+---
+
+### 2. Test Agent (`test`)
+
+**Specialization**: Testing, quality assurance, validation
+
+**Use When**:
+- Writing new tests
+- Validating feature implementations
+- Running test suites
+- Debugging test failures
+
+**Key Files**:
+- `tests/test-runtime.js` - Runtime tests
+- `tests/test-v1.5.0.js` - Integration tests
+- `tests/test-v1.5.0-simple.sh` - Static checks
+- `tests/README.md` - Test documentation
+
+**Guidelines**:
+- Test both success and failure paths
+- Include edge cases
+- Document test requirements
+- Keep tests independent
+
+---
+
+### 3. Docs Agent (`docs`)
+
+**Specialization**: Documentation, README updates, changelog
+
+**Use When**:
+- Updating README.md
+- Writing feature documentation
+- Updating CHANGELOG.md
+- Creating usage examples
+
+**Key Files**:
+- `README.md` - Main documentation
+- `CHANGELOG.md` - Version history
+- `CLAUDE.md` - Development guidelines
+- `ai_docs/` - AI-specific docs
+
+**Guidelines**:
+- Keep examples practical
+- Update all relevant docs together
+- Maintain consistent formatting
+- Include version numbers
+
+---
+
+### 4. Review Agent (`review`)
+
+**Specialization**: Code review, architecture validation, quality checks
+
+**Use When**:
+- Reviewing PRs
+- Validating architectural decisions
+- Checking for breaking changes
+- Security audits
+
+**Guidelines**:
+- Check for backward compatibility
+- Validate error handling
+- Review test coverage
+- Check documentation updates
+
+---
+
+### 5. Release Agent (`release`)
+
+**Specialization**: Version management, npm publishing, releases
+
+**Use When**:
+- Preparing a new release
+- Updating version numbers
+- Creating GitHub releases
+- Publishing to npm
+
+**Key Files**:
+- `package.json` - Version, metadata
+- `CHANGELOG.md` - Release notes
+- `dist/` - Built output
+
+**Guidelines**:
+- Follow semantic versioning
+- Update CHANGELOG.md
+- Test build before release
+- Verify npm package contents
+
+---
+
+## Routing Guidelines
+
+### Simple Tasks (No Agent Needed)
+- Quick fixes with clear solutions
+- Single-file changes
+- Documentation typos
+- Minor refactoring
+
+### Code Agent Tasks
+- "Add a new tool for X"
+- "Fix bug in memory storage"
+- "Implement feature Y"
+- "Optimize Redis queries"
+
+### Test Agent Tasks
+- "Write tests for X feature"
+- "Why is test Y failing?"
+- "Validate feature implementation"
+- "Add edge case coverage"
+
+### Docs Agent Tasks
+- "Update README for new feature"
+- "Document X functionality"
+- "Add usage examples"
+- "Update CHANGELOG"
+
+### Review Agent Tasks
+- "Review this implementation"
+- "Check for breaking changes"
+- "Validate architecture decision"
+- "Security review"
+
+### Release Agent Tasks
+- "Prepare v1.7.0 release"
+- "Publish to npm"
+- "Create GitHub release"
+- "Update version numbers"
+
+---
+
+## Agent Invocation
+
+The Coordinator should:
+
+1. **Analyze the task** to determine complexity and scope
+2. **Select appropriate agent** based on specialization
+3. **Provide context** from globals.md and relevant files
+4. **Track progress** in todo.json
+5. **Validate output** before completion
+
+---
+
+## Creating New Agents
+
+When adding new agents:
+
+1. Define clear specialization
+2. List key files and responsibilities
+3. Provide specific guidelines
+4. Add routing examples
+5. Update this registry

package/.claude/globals.md

@@ -0,0 +1,168 @@
+# Global Configuration - Recall MCP Server
+
+## Project Overview
+
+**Recall** is an MCP (Model Context Protocol) server providing persistent memory for Claude conversations. It stores context in Redis with semantic search capabilities, solving context window limitations.
+
+**Version**: 1.6.0
+**Author**: José Airosa
+**License**: MIT
+
+---
+
+## Tech Stack
+
+- **Runtime**: Node.js 18+
+- **Language**: TypeScript (strict mode)
+- **Build**: tsup
+- **Database**: Redis (ioredis)
+- **AI**: Anthropic Claude API (for embeddings/analysis)
+- **Protocol**: Model Context Protocol (MCP)
+- **IDs**: ULID (not auto-increment)
+
+---
+
+## Key Architecture
+
+### Core Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| Entry Point | `src/index.ts` | MCP server setup, request routing |
+| Types | `src/types.ts` | Zod schemas, TypeScript types |
+| Memory Store | `src/redis/memory-store.ts` | Redis storage logic |
+| Redis Client | `src/redis/client.ts` | Connection management |
+| Embeddings | `src/embeddings/generator.ts` | Claude-based embeddings |
+| Analyzer | `src/analysis/conversation-analyzer.ts` | AI conversation analysis |
+
+### Tool Modules
+
+| Module | Purpose |
+|--------|---------|
+| `tools/index.ts` | Core memory operations |
+| `tools/context-tools.ts` | Smart context (recall, analyze, summarize) |
+| `tools/export-import-tools.ts` | Backup/restore, duplicates |
+| `tools/relationship-tools.ts` | Knowledge graphs (v1.4) |
+| `tools/version-tools.ts` | Version history (v1.5) |
+| `tools/template-tools.ts` | Memory templates (v1.5) |
+| `tools/category-tools.ts` | Categories (v1.5) |
+
+### Resources
+
+| Module | Purpose |
+|--------|---------|
+| `resources/index.ts` | MCP resource handlers |
+| `resources/analytics.ts` | Usage analytics |
+
+---
+
+## Critical Constraints
+
+### NEVER Change Without Migration
+
+1. **Redis Key Patterns**:
+   - `memory:{id}` → Hash
+   - `memories:all` → Set
+   - `memories:timeline` → Sorted Set
+   - `memories:type:{type}` → Set
+   - `memories:tag:{tag}` → Set
+   - `memories:important` → Sorted Set
+
+2. **Context Types** (10 core types):
+   - `directive`, `information`, `heading`, `decision`, `code_pattern`
+   - `requirement`, `error`, `todo`, `insight`, `preference`
+
+3. **Importance Threshold**: >= 8 for `memories:important` index
+
+4. **ULID Generation**: Memory IDs must remain accessible forever
+
+---
+
+## Code Conventions
+
+### Naming
+- **Files**: kebab-case (`memory-store.ts`)
+- **Variables/Functions**: camelCase
+- **Types/Classes**: PascalCase
+- **Constants**: SCREAMING_SNAKE_CASE
+
+### Imports
+- Use `.js` extensions (ESM requirement)
+- Group: stdlib → vendor → local
+
+### Error Handling
+- Use MCP error codes: `ErrorCode.InvalidRequest`, `ErrorCode.InternalError`
+- Always include descriptive messages
+
+---
+
+## Testing
+
+### Quick Commands
+```bash
+# Build
+npm run build
+
+# Static checks
+./tests/test-v1.5.0-simple.sh
+
+# Runtime tests (requires Redis)
+ANTHROPIC_API_KEY="test-key" node tests/test-runtime.js
+```
+
+### Before Committing
+- [ ] TypeScript compiles
+- [ ] Bundle size reasonable
+- [ ] All tools work
+- [ ] Indexes update correctly
+- [ ] Documentation updated
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `REDIS_URL` | No | `redis://localhost:6379` | Redis connection |
+| `ANTHROPIC_API_KEY` | Yes | - | Claude API for embeddings |
+| `WORKSPACE_MODE` | No | `isolated` | Memory isolation mode |
+
+---
+
+## Workspace Modes
+
+- **isolated** (default): Workspace-only memories
+- **global**: All memories shared globally
+- **hybrid**: Both workspace-specific AND global memories
+
+---
+
+## Performance Targets
+
+- Store Memory: ~200ms
+- Batch Store (10): ~500ms
+- Get by ID: <1ms
+- Recent (50): ~10ms
+- Semantic Search (1k): ~500ms
+- Semantic Search (10k): ~2s
+
+---
+
+## Security Reminders
+
+- Redis should be secured (AUTH, TLS)
+- Never store secrets in memories
+- Audit stored data regularly
+- Use `rediss://` for remote connections
+
+---
+
+## Coordinator Role
+
+When working as the Coordinator on this project:
+
+1. **Route to Specialists**: Use agents in `.claude/agents/` for specialized tasks
+2. **Track Progress**: Keep `.claude/todo.json` updated
+3. **Maintain Quality**: Ensure tests pass before commits
+4. **Preserve Compatibility**: Never break existing memories
+5. **Document Changes**: Update CHANGELOG.md and README.md

package/.claude/settings.local.json

@@ -2,7 +2,21 @@
   "permissions": {
     "allow": [
       "Bash(gh pr merge:*)",
-      "Bash(npm publish:*)"
+      "Bash(npm publish:*)",
+      "Bash(gh release create:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(npm run build:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$(cat <<''EOF''\nfix: Clean up PR - remove dist/, fix unused imports, improve docs\n\n- Remove dist/ from git tracking (added to .gitignore)\n- Remove unused imports in memory-store.ts (Redis, log, unused providers)\n- Fix storage-client.interface.ts - remove unused import, improve typing\n- Fix CHANGELOG.md - proper markdown formatting and expanded release notes\n- Fix README.md - properly close code blocks, fix markdown structure\n- Fix QUICKSTART.md - replace hardcoded paths with placeholders, fix JSON\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n)\")",
+      "Bash(git push:*)",
+      "Bash(cat:*)",
+      "Bash(git checkout:*)",
+      "Bash(git pull:*)",
+      "Bash(git merge valkey-support --no-ff -m \"$(cat <<''EOF''\nfeat: v1.7.0 - Valkey Support (#10)\n\nAdd Valkey as an alternative backend to Redis with a clean storage abstraction layer.\n\n## Added\n- Valkey support via @valkey/valkey-glide client\n- BACKEND_TYPE env var to select backend (redis/valkey)\n- VALKEY_HOST and VALKEY_PORT configuration options\n- StorageClient interface for backend-agnostic operations\n- RedisAdapter and ValkeyAdapter implementations\n- Factory pattern for backend selection\n\n## Changed\n- Moved persistence code to src/persistence/ directory\n- Ported JavaScript tests to TypeScript\n\n## Fixed\n- Removed dist/ from git tracking\n- Cleaned up unused imports\n- Fixed markdown formatting in docs\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nCo-Authored-By: Matthias Howell <matthias.howell@yoppworks.com>\nEOF\n)\")",
+      "Bash(git reset:*)",
+      "Bash(git rm:*)",
+      "Bash(gh pr create:*)"
     ],
     "deny": [],
     "ask": []

package/.claude/todo.json

@@ -0,0 +1,7 @@
+{
+  "version": "1.0.0",
+  "lastUpdated": "2025-12-03T00:00:00Z",
+  "tasks": [],
+  "completed": [],
+  "notes": "Task tracking for Recall MCP Server development. Keep this updated during work sessions."
+}

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.7.0] - 2025-12-03
+
+### Added
+
+- **Valkey Support** - Now supports Valkey as an alternative backend to Redis
+  - New `BACKEND_TYPE` environment variable to select backend (`redis` or `valkey`)
+  - `VALKEY_HOST` and `VALKEY_PORT` configuration options
+  - Uses `@valkey/valkey-glide` client for Valkey connections
+  - Full feature parity with Redis backend
+
+### Changed
+
+- **Architecture Refactor** - Introduced storage abstraction layer
+  - New `StorageClient` interface for backend-agnostic storage operations
+  - `RedisAdapter` and `ValkeyAdapter` implement the common interface
+  - Factory pattern (`createStorageClient`) for backend selection
+  - Moved persistence code to `src/persistence/` directory
+
+### Fixed
+
+- Ported JavaScript tests to TypeScript for better type safety
+
+---
+
 ## [1.6.0] - 2025-10-04
 
 ### Added

package/CLAUDE.md

@@ -6,7 +6,7 @@ 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.
+This is an MCP (Model Context Protocol) server that provides **long-term memory** for Claude conversations. It stores context in Redis or Valkey 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.
 
@@ -107,10 +107,10 @@ Use this tool to retrieve consolidated context from specific time periods:
 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
+4. **Atomic Operations**: Use Redis/Valkey pipelines for multi-step updates
 5. **Error Handling**: Use MCP error codes (`ErrorCode.InvalidRequest`, `ErrorCode.InternalError`)
 
-### Redis Data Model
+### Redis/Valkey Data Model
 
 **NEVER** change these key patterns without migration:
 ```
@@ -147,7 +147,7 @@ These 10 types are core to the system:
 ### 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)
+2. Add method to `MemoryStore` class in [memory-store.ts](src/persistence/memory-store.ts)
 3. Add tool handler to [tools/index.ts](src/tools/index.ts)
 4. Update documentation in [README.md](README.md)
 
@@ -162,7 +162,7 @@ These 10 types are core to the system:
 
 **CRITICAL**: If changing `MemoryStore` methods:
 1. Ensure index updates are atomic (use pipelines)
-2. Test with existing Redis data
+2. Test with existing Redis/Valkey data
 3. Document migration path if needed
 4. Update version in [package.json](package.json)
 
@@ -234,7 +234,7 @@ export const ContextType = z.enum([
 ### Increase Embedding Dimensions
 
 If switching to larger embedding model:
-1. Update `embedding` field handling in [memory-store.ts](src/redis/memory-store.ts)
+1. Update `embedding` field handling in [memory-store.ts](src/persistence/memory-store.ts)
 2. Existing memories will have wrong dimensions - need migration
 3. Consider versioning: `embedding_v1`, `embedding_v2`
 
@@ -244,7 +244,7 @@ If switching to larger embedding model:
 
 **Current**: No formal migration system
 
-**If Redis Schema Changes**:
+**If Redis/Valkey Schema Changes**:
 1. Create migration script in `scripts/migrate-{version}.ts`
 2. Document in `MIGRATIONS.md`
 3. Provide rollback instructions

package/MEMORY_RELATIONSHIPS.md

@@ -316,7 +316,7 @@ Claude: [Uses get_related_memories with filter 'supersedes']
 
 ### Storage
 
-**Redis Keys:**
+**Redis/Valkey Keys:**
 ```
 # Workspace relationships
 ws:{workspace_id}:relationship:{id}

package/QUICKSTART.md

@@ -2,6 +2,8 @@
 
 ## Setup (5 minutes)
 
+## Redis Version (See Valkey Below)
+
 ### 1. Start Redis
 
 ```bash
@@ -35,7 +37,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "memory": {
       "command": "node",
-      "args": ["/Users/joseairosa/Development/mcp/mem/dist/index.js"],
+      "args": ["/path/to/recall/dist/index.js"],
       "env": {
         "REDIS_URL": "redis://localhost:6379",
         "OPENAI_API_KEY": "sk-your-openai-key"
@@ -147,3 +149,151 @@ Make sure your API key is set in the Claude Desktop config, not just in `.env`.
 ---
 
 **Ready to use!** Your Claude now has a persistent memory brain.
+
+### 1. Start Valkey
+
+```bash
+# macOS
+brew services start valkey
+
+# Verify Valkey is running - if installed with brew
+valkey-cli ping  # Should return PONG
+
+# Or Docker
+docker run -d -p 6379:6379 valkey/valkey:latest
+
+# use docker to ping Valkey server
+docker exec -it [valkey container name] valkey-cli ping
+```
+
+### 2. Set Environment Variables
+
+```bash
+# Copy example env file
+cp .env.example .env
+
+# Edit .env and add your Valkey values
+# BACKEND_TYPE='valkey'
+# VALKEY_HOST = 'localhost'
+# VALKEY_PORT = '6379'
+
+```
+
+### 3. Configure Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "node",
+      "args": ["/path/to/recall/dist/index.js"],
+      "env": {
+        "BACKEND_TYPE": "valkey",
+        "VALKEY_HOST": "localhost",
+        "VALKEY_PORT": "6379"
+      }
+    }
+  }
+}
+```
+
+### 4. Restart Claude Desktop
+
+Completely quit and reopen Claude Desktop to load the MCP server.
+
+---
+
+## First Test
+
+Ask Claude:
+
+> "Store a memory that I prefer informal communication. Make it importance 8 and tag it with 'preference' and 'communication'"
+
+Claude should use the `store_memory` tool and return a success message with a memory ID.
+
+Then ask:
+
+> "Search for memories about communication preferences"
+
+Claude should use the `search_memories` tool and find your stored memory.
+
+---
+
+## Common Usage Patterns
+
+### Store Important Directive
+
+> "Remember: Always use ULIDs for database IDs, never auto-increment. This is critical (importance 10)"
+
+### Store Code Pattern
+
+> "Store a code pattern: In this project, use Drizzle ORM with text('id').primaryKey() for ULID fields. Tag it with 'drizzle', 'database', and 'patterns'"
+
+### Search Previous Context
+
+> "What do you remember about database conventions?"
+
+### Get Recent Context
+
+> "Show me the last 10 memories we've stored"
+
+### Create Session Snapshot
+
+> "Create a session called 'Feature X Development - Day 1' with the last 5 memories"
+
+### Retrieve Session
+
+> "Show me memories from the 'Feature X Development - Day 1' session"
+
+---
+
+## Verification
+
+Check if server is running:
+
+```bash
+# Check Claude Desktop logs
+tail -f ~/Library/Logs/Claude/mcp*.log
+
+# Should see:
+# Valkey Client Connected
+# Valkey Client Ready
+# MCP Memory Server started successfully
+```
+
+---
+
+## Troubleshooting
+
+### "Failed to connect to Redis"
+
+```bash
+# Check Redis is running
+valkey-cli ping
+
+# Start Redis if not running
+brew services start valkey
+```
+
+### Server not appearing in Claude
+
+1. Check config file syntax (valid JSON)
+2. Verify absolute path to `dist/index.js`
+3. Completely quit and restart Claude Desktop
+4. Check logs: `~/Library/Logs/Claude/`
+
+---
+
+## Next Steps
+
+- Store project-specific conventions and directives
+- Create sessions at the end of each work day
+- Use semantic search to find relevant past context
+- Tag memories for easy retrieval
+- Mark critical information with high importance scores
+
+---
+
+**Ready to use!** Your Claude now has a persistent memory brain.