@joseairosa/recall 1.5.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

@@ -1,25 +1,22 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npm install)",
-      "Bash(git mv:*)",
+      "Bash(gh pr merge:*)",
+      "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:*)",
-      "Bash(git remote 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(npm view:*)",
-      "Bash(npm whoami:*)",
-      "Bash(curl:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm publish:*)",
-      "Bash(gh pr create:*)",
-      "Bash(gh repo edit:*)",
       "Bash(cat:*)",
       "Bash(git checkout:*)",
       "Bash(git pull:*)",
-      "Bash(node:*)",
-      "Read(//Users/joseairosa/Library/**)",
-      "Bash(gh pr merge:*)"
+      "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": []
@@ -27,4 +24,4 @@
   "enabledMcpjsonServers": [
     "memory"
   ]
-}
+}

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,64 @@ 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
+- **Time Window Context Retrieval** - Get all memories from specific time periods
+  - `get_time_window_context` tool for time-based memory retrieval
+  - Multiple time specifications: hours, minutes, or explicit timestamp ranges
+  - Three output formats: Markdown (default), JSON, and plain text
+  - Four grouping options: chronological, by type, by importance, or by tags
+  - Filtering by minimum importance and context types
+  - Perfect for building context files from work sessions
+  - Respects workspace modes (isolated/global/hybrid)
+
+- **Best Practices Documentation** - Context bloat prevention
+  - Added guidelines for selective memory storage
+  - Clear examples of what to store vs. avoid
+  - Added to both README.md and CLAUDE.md
+  - Helps users avoid indiscriminate memory storage
+
+### Technical
+- New `GetTimeWindowContextSchema` in types.ts
+- New `getMemoriesByTimeWindow()` method in MemoryStore
+- Helper functions for formatting output (JSON, Markdown, Text)
+- Uses Redis `ZRANGEBYSCORE` for efficient time-range queries
+
+### Testing
+- New `test-time-window.js` test suite with 8 tests
+- All tests passing
+- Test coverage for time-based retrieval, filtering, grouping
+
+### Tool Count
+- **28 tools** (was 27 in v1.5.0)
+
+---
+
 ## [1.5.0] - 2025-10-03
 
 ### Added

package/CLAUDE.md

@@ -6,12 +6,93 @@ 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.
 
 ---
 
+## Using Recall Efficiently (Context Bloat Prevention)
+
+**IMPORTANT: Be selective with memory storage to avoid context bloat.**
+
+### When to Store Memories
+
+Store **HIGH-SIGNAL** context only:
+- ✅ High-level decisions and reasoning ("We chose PostgreSQL over MongoDB because...")
+- ✅ Project preferences (coding style, tech stack, architecture patterns)
+- ✅ Critical constraints (API limits, business rules, security requirements)
+- ✅ Learned patterns from bugs/solutions ("Avoid X because it causes Y")
+
+### When NOT to Store
+
+Don't store **LOW-SIGNAL** content:
+- ❌ Code snippets or implementations (put those in files)
+- ❌ Obvious facts or general knowledge
+- ❌ Temporary context (only needed in current session)
+- ❌ Duplicates of what's already in documentation
+
+### Keep Memories Concise
+
+**Examples:**
+- ✅ GOOD: "API rate limit is 1000 req/min, prefer caching for frequently accessed data"
+- ❌ BAD: "Here's the entire implementation of our caching layer: [50 lines of code]"
+
+- ✅ GOOD: "Team prefers Tailwind CSS over styled-components for consistency"
+- ❌ BAD: "Tailwind is a utility-first CSS framework that..."
+
+**Remember:** Recall is for high-level context, not a code repository. Quality over quantity.
+
+---
+
+## Time Window Context Retrieval (v1.6.0+)
+
+### When to Use `get_time_window_context`
+
+Use this tool to retrieve consolidated context from specific time periods:
+
+**Perfect for:**
+- 📋 Building context files from work sessions ("Give me everything from the last 2 hours as markdown")
+- 🔄 Session handoffs ("Show me what we worked on in the last hour")
+- 📊 Progress summaries ("Get all decisions from today")
+- 📝 Documentation ("Export the last 4 hours as a context file")
+
+**How to use:**
+```
+"Give me the context for the last 2 hours"
+"Show me all high-importance memories from the last hour, grouped by type"
+"Export the last 30 minutes as JSON"
+```
+
+### Output Format Options
+
+- **Markdown** (default): Clean formatted context ready to paste
+- **JSON**: Structured data for processing
+- **Text**: Simple plain text summary
+
+### Grouping Options
+
+- **Chronological**: Time-ordered (default, oldest to newest)
+- **By type**: Grouped by context_type (decisions, patterns, etc.)
+- **By importance**: High to low priority
+- **By tags**: Organized by tag categories
+
+### Best Practices
+
+**DO:**
+- ✅ Use for building context files after work sessions
+- ✅ Filter by importance (>= 8) for critical context only
+- ✅ Group by type when exporting for specific purposes
+- ✅ Use markdown format for human-readable output
+- ✅ Use JSON format when passing to external tools
+
+**DON'T:**
+- ❌ Retrieve huge time windows (>24 hours) without filtering
+- ❌ Use when semantic search would be better (use `search_memories` instead)
+- ❌ Store the output as another memory (creates redundancy)
+
+---
+
 ## Development Guidelines
 
 ### Code Style
@@ -26,10 +107,10 @@ This is an MCP (Model Context Protocol) server that provides **long-term memory*
 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:
 ```
@@ -66,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)
 
@@ -81,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)
 
@@ -153,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`
 
@@ -163,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}