Content
# Recall 🧠 (Redis or Valkey Compatible)
**Give Claude perfect recall with persistent memory that survives context limits and session restarts.**
Your AI assistant can now remember important context, decisions, and patterns across all conversations—no more repeating yourself or losing critical information when the context window fills up.
---
## ⚠️ Security & Privacy Disclaimer
**IMPORTANT: READ BEFORE USE**
Recall stores conversation memories in either **Redis** or **Valkey**, which may contain sensitive information including:
- Code snippets, API keys, credentials, and secrets discussed in conversations
- Business logic, architecture decisions, and proprietary information
- Personal data, team member names, and organizational details
- Any other context shared with Claude during conversations
**You are responsible for:**
1. **Redis/Valkey Security**: Ensure your memory store is properly secured with authentication, TLS encryption, and network access controls
2. **Data Ownership**: Only use Redis/Valkey servers that YOU control or have explicit permission to use
3. **Access Control**: Understand who has access to your memory store and stored memories
4. **Sensitive Data**: Never store memories on shared/public instances if they contain sensitive information
5. **Compliance**: Ensure your use complies with your organization's data policies and relevant regulations (GDPR, CCPA, etc.)
**Disclaimer of Liability:**
THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. THE AUTHOR (JOSÉ AIROSA) IS NOT LIABLE FOR:
- Data breaches, leaks, or unauthorized access to stored memories
- Loss of data or corrupted memories
- Compliance violations or regulatory issues
- Any damages arising from the use or misuse of this software
By using Recall, you acknowledge that you understand these risks and accept full responsibility for:
- Securing your Redis or Valkey infrastructure
- Managing access to stored memories
- Protecting sensitive information
- Compliance with applicable laws and regulations
**Best Practices:**
- Use dedicated Redis or Valkey instances with strong authentication
- Enable TLS/SSL encryption (`rediss://`) for remote connections
- Regularly audit stored memories for sensitive data
- Implement access controls and firewall rules
- Use separate databases for different security contexts
- Consider data retention policies and periodic cleanup
- Never share connection strings publicly
---
## What is This?
Recall is a **brain extension** for Claude that stores memories in Redis or Valkey. It solves the context window problem by:
- 📝 **Remembering** directives, decisions, code patterns, and important information
- 🔍 **Retrieving** relevant context automatically when you need it
- 🔄 **Persisting** across sessions – memories survive restarts and context compaction
- 🗂️ **Organizing** by workspace – Project A memories don't pollute Project B
---
## Quick Start (5 Minutes)
### 1. Prerequisites
- **Redis** or **Valkey** running locally (`localhost:6379`)
- **Node.js** 18 or higher
- **Claude Code** or **Claude Desktop**
**Option A: Local Redis**
```bash
# macOS
brew install redis
brew services start redis
# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis
# Docker
docker run -d -p 6379:6379 redis:latest
```
**Option B: Local Valkey**
```bash
# macOS
brew install valkey
brew services start valkey
# Docker
docker run -d -p 6379:6379 valkey/valkey:latest
```
**Option C: Cloud Redis (No local install needed)**
Use a free Redis cloud service:
- **[Upstash](https://upstash.com/)** - Free tier with 500,000 commands/month
- **[Redis Cloud](https://redis.com/try-free/)** - Free 30MB database
- **[Railway](https://railway.app/)** - Free Redis with credit
Then use the provided connection URL in your config:
```json
{
"env": {
"REDIS_URL": "rediss://default:password@your-redis-host.com:6379"
}
}
```
**Option D: Cloud Valkey (No local install needed)**
Most cloud providers offer Valkey services with free or low-cost trials available:
- **[AWS ElastiCache](https://aws.amazon.com/elasticache/)** - Use free tier to try it out
- **[AWS Free Tier](https://aws.amazon.com/free/)** - General AWS free tier options
### 2. Install
**Option A: Using Claude CLI (Recommended)**
```bash
npx @modelcontextprotocol/create-server @joseairosa/recall
```
Or use the MCP command directly in your Claude configuration (no installation needed):
```json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": ["-y", "@joseairosa/recall"]
}
}
}
```
**Option B: Global installation**
```bash
npm install -g @joseairosa/recall
```
**Option C: From source**
```bash
git clone https://github.com/joseairosa/recall.git
cd recall
npm install
npm run build
```
### 3. Configure Claude
Add to your Claude configuration file:
**Claude Code** (`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
```json
{
"mcpServers": {
"recall": {
"command": "recall",
"env": {
"REDIS_URL": "redis://localhost:6379",
"ANTHROPIC_API_KEY": "your-api-key-here"
}
}
}
}
```
or for Valkey:
```json
{
"mcpServers": {
"recall": {
"command": "recall",
"env": {
"BACKEND_TYPE":"valkey",
"VALKEY_HOST":"localhost",
"VALKEY_PORT":6379 ,
"ANTHROPIC_API_KEY": "your-api-key-here"
}
}
}
}
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": ["-y", "@joseairosa/recall"],
"env": {
"REDIS_URL": "redis://localhost:6379",
"ANTHROPIC_API_KEY": "your-api-key-here"
}
}
}
}
```
or for Valkey:
```json
{
"mcpServers": {
"recall": {
"command": "recall",
"env": {
"BACKEND_TYPE":"valkey",
"VALKEY_HOST":"localhost",
"VALKEY_PORT":6379 ,
"ANTHROPIC_API_KEY": "your-api-key-here"
}
}
}
}
```
### 4. Restart Claude
Restart Claude Code or Claude Desktop to load the MCP server.
### 5. Test It!
Ask Claude:
```
"Store a memory that I prefer using TypeScript for all new projects"
```
Then in a new conversation:
```
"What do you know about my coding preferences?"
```
✨ **It remembers!**
---
## Upgrading
### Automatic Updates (Recommended)
If you use **`npx -y @joseairosa/recall`** in your config, you **automatically get the latest version** on every Claude restart. No action needed! 🎉
```json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": ["-y", "@joseairosa/recall"] // ← Always fetches latest
}
}
}
```
### Manual Updates
**If using global installation:**
```bash
# Update to latest version
npm update -g @joseairosa/recall
# Or install specific version
npm install -g @joseairosa/recall@1.3.0
# Check installed version
npm list -g @joseairosa/recall
```
**If using from source:**
```bash
cd recall
git pull origin main
npm install
npm run build
```
**After updating:**
1. Restart Claude Code or Claude Desktop
2. Verify new version: Ask Claude "What Recall version are you using?"
3. Check CHANGELOG.md for new features and breaking changes
### Version-Specific Upgrades
**Upgrading to v1.3.0:**
- No breaking changes, fully backward compatible
- To use global memories: Add `WORKSPACE_MODE=hybrid` to your config
- See [Migration Guide](#migrating-from-v121-to-v130) below
---
## How to Use
### ⚠️ Best Practices: Avoid Context Bloat
**Be selective with memory storage to keep Claude efficient.**
**Store HIGH-SIGNAL context:**
- ✅ Project preferences (coding style, tech stack, architecture patterns)
- ✅ Critical decisions ("We chose PostgreSQL over MongoDB because...")
- ✅ Important constraints (API limits, business rules, security requirements)
- ✅ Learned patterns from bugs/solutions
**Don't store LOW-SIGNAL content:**
- ❌ Code snippets (put those in files instead)
- ❌ Obvious facts or general knowledge
- ❌ Temporary context (only needed in current session)
- ❌ Duplicates of what's in documentation
**Keep memories concise:**
- ✅ Good: "API rate limit is 1000 req/min, prefer caching for frequent data"
- ❌ Bad: "Here's the entire implementation of our caching layer: [50 lines of code]"
**Remember:** Recall is for high-level context, not a code repository. Quality over quantity keeps your context window efficient.
---
### Store Important Information
Claude can automatically extract and store memories, or you can be explicit:
**Natural language:**
```
"Remember that our API base URL is https://api.example.com/v2"
```
```
"Store this as a directive: Always use functional components in React"
```
**What Claude does:** Uses the `store_memory` tool to save this information with appropriate context type and importance.
**Store globally (v1.3+):**
```
"Remember globally: I prefer TypeScript strict mode for all projects"
```
```
"Store this as a global preference: Always use ULIDs for database IDs"
```
**What Claude does:** Uses `store_memory` with `is_global: true` to make it accessible across all workspaces (requires `WORKSPACE_MODE=hybrid` or `global`).
### Recall Context
Claude automatically retrieves relevant memories, but you can also ask:
```
"What do you remember about our database schema?"
```
```
"Recall any decisions we made about error handling"
```
**What Claude does:** Uses `recall_relevant_context` or `search_memories` to find related information.
### Analyze Conversations
Before context compaction, preserve important details:
```
"Analyze our conversation and remember the important parts"
```
**What Claude does:** Uses `analyze_and_remember` to extract structured memories from the conversation.
### Organize Sessions
Group related work:
```
"Summarize this session and save it as 'Authentication Refactoring'"
```
**What Claude does:** Uses `summarize_session` to create a session snapshot with all relevant memories.
### Get Time Window Context (v1.6+)
Retrieve all memories from a specific time period:
```
"Give me the context for the last 2 hours"
```
```
"Show me everything from the last 30 minutes, formatted as markdown"
```
```
"Get all high-importance memories from the last hour, grouped by type"
```
**What Claude does:** Uses `get_time_window_context` to retrieve and format memories from the specified time window.
**Options:**
- Time specification: hours, minutes, or explicit timestamps
- Output formats: markdown (default), JSON, or plain text
- Grouping: chronological, by type, by importance, or by tags
- Filtering: minimum importance, specific context types
**Example outputs:**
- **Markdown**: Clean formatted context ready to paste into documentation
- **JSON**: Structured data for external processing
- **Text**: Simple plain text summary
Perfect for building context files from work sessions or exporting specific time periods.
### Convert Memories (v1.3+)
**Promote workspace memory to global:**
```
"Convert this memory to global: mem_abc123"
```
**What Claude does:** Uses `convert_to_global` to move the memory from workspace-specific to globally accessible.
**Convert back to workspace:**
```
"Convert this global memory to workspace-specific: mem_xyz789"
```
**What Claude does:** Uses `convert_to_workspace` to move the memory from global to current workspace.
### Link Related Memories (v1.4+)
**Create relationships between memories:**
```
"Link these two memories: pattern mem_abc123 is an example of implementation mem_xyz789"
```
**What Claude does:** Uses `link_memories` to create an `example_of` relationship between the memories.
**Find related memories:**
```
"Show me all memories related to mem_abc123"
```
**What Claude does:** Uses `get_related_memories` to traverse the relationship graph and find connected memories.
**Remove a relationship:**
```
"Unlink relationship rel_123abc"
```
**What Claude does:** Uses `unlink_memories` to remove the relationship while keeping both memories intact.
### Version History & Rollback (v1.5+)
**View version history:**
```
"Show me the version history for memory mem_abc123"
```
**What Claude does:** Uses `get_memory_history` to retrieve all versions with timestamps and change reasons.
**Rollback to previous version:**
```
"Rollback memory mem_abc123 to version ver_xyz789"
```
**What Claude does:** Uses `rollback_memory` to restore the memory to the specified version while preserving relationships.
### Memory Templates (v1.5+)
**Create a template:**
```
"Create a template for bug reports with fields: {{title}}, {{severity}}, {{steps}}"
```
**What Claude does:** Uses `create_template` to save a reusable template with placeholders.
**Use a template:**
```
"Create a memory from bug template: title='Login fails', severity='high', steps='1. Click login 2. Error appears'"
```
**What Claude does:** Uses `create_from_template` to instantiate a memory with filled-in variables.
### Categories (v1.5+)
**Assign category:**
```
"Categorize memory mem_abc123 as 'authentication'"
```
**What Claude does:** Uses `set_memory_category` to organize the memory.
**List categories:**
```
"Show me all categories with memory counts"
```
**What Claude does:** Uses `list_categories` to display all categories and their sizes.
**Get memories by category:**
```
"Show me all memories in the 'authentication' category"
```
**What Claude does:** Uses `get_memories_by_category` to retrieve all memories in that category.
### Advanced Search (v1.5+)
**Fuzzy search:**
```
"Search for 'authentification' with fuzzy matching"
```
**What Claude does:** Uses `search_memories` with `fuzzy: true` to find similar words despite typos.
**Regex search:**
```
"Find memories matching the pattern 'API.*v[0-9]+'"
```
**What Claude does:** Uses `search_memories` with `regex` parameter for pattern-based search.
**Category filtering:**
```
"Search for 'login' only in the 'authentication' category"
```
**What Claude does:** Uses `search_memories` with both `query` and `category` parameters.
---
## Memory Types
Memories are categorized for better organization:
| Type | Purpose | Example |
|------|---------|---------|
| **`directive`** | Rules, guidelines, preferences | "Always use TypeScript strict mode" |
| **`decision`** | Important choices and rationale | "Chose PostgreSQL over MongoDB for ACID" |
| **`code_pattern`** | Reusable code patterns | "Use async/await, not .then()" |
| **`requirement`** | Feature requirements | "Must support 10k concurrent users" |
| **`information`** | General facts and context | "API endpoint is /api/v2/users" |
| **`heading`** | Project structure markers | "Authentication Module" |
| **`error`** | Known issues and solutions | "CORS fixed by adding headers" |
| **`todo`** | Tasks and reminders | "Add rate limiting to API" |
| **`insight`** | Learnings and observations | "Bottleneck is in database indexes" |
| **`preference`** | Personal or team preferences | "Prefer concise communication" |
---
## Available Tools (27)
Claude has access to these memory tools:
### Core Memory
- **`store_memory`** - Store a single memory
- **`store_batch_memories`** - Store multiple memories at once
- **`update_memory`** - Update existing memory (auto-creates version in v1.5+)
- **`delete_memory`** - Remove a memory
- **`search_memories`** - Search using semantic similarity (enhanced in v1.5+ with category/fuzzy/regex)
- **`organize_session`** - Create session groups
### Smart Context (v1.1+)
- **`recall_relevant_context`** - Proactively retrieve relevant memories
- **`analyze_and_remember`** - Extract and store memories from conversation
- **`summarize_session`** - Create session snapshot
### Advanced (v1.2+)
- **`export_memories`** - Backup to JSON
- **`import_memories`** - Restore from JSON
- **`find_duplicates`** - Detect similar memories
- **`consolidate_memories`** - Merge multiple memories
### Global Memories (v1.3+)
- **`convert_to_global`** - Convert workspace memory to global
- **`convert_to_workspace`** - Convert global memory to workspace-specific
### Memory Relationships (v1.4+)
- **`link_memories`** - Create relationships between memories
- **`get_related_memories`** - Traverse relationship graph
- **`unlink_memories`** - Remove relationships
- **`get_memory_graph`** - Get full memory graph structure
### Version History (v1.5+)
- **`get_memory_history`** - View version history of a memory
- **`rollback_memory`** - Rollback to a previous version
### Templates (v1.5+)
- **`create_template`** - Create reusable memory template
- **`create_from_template`** - Instantiate memory from template
- **`list_templates`** - List available templates
### Categories (v1.5+)
- **`set_memory_category`** - Assign category to a memory
- **`list_categories`** - List all categories with counts
- **`get_memories_by_category`** - Retrieve memories by category
---
## Available Resources (17)
Browse memories directly using MCP resources:
### Workspace Resources
- **`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://sessions`** - All sessions
- **`memory://session/{id}`** - Specific session
- **`memory://summary`** - Statistics overview
- **`memory://search?q=query`** - Semantic search
- **`memory://analytics`** - Usage analytics dashboard (v1.2+)
### Global Resources (v1.3+)
- **`memory://global/recent`** - Recent global memories (cross-workspace)
- **`memory://global/by-type/{type}`** - Global memories by context type
- **`memory://global/by-tag/{tag}`** - Global memories by tag
- **`memory://global/important`** - Important global memories
- **`memory://global/search?q=query`** - Search global memories
### Relationship Resources (v1.4+)
- **`memory://relationships`** - List all memory relationships
- **`memory://memory/{id}/related`** - Get related memories
- **`memory://graph/{id}`** - Get memory graph structure
---
## Workspace Isolation
Memories are **automatically isolated by directory**. Working in different projects? No problem:
```
/Users/you/project-a/ → Workspace A memories
/Users/you/project-b/ → Workspace B memories
```
Memories from Project A **never pollute** Project B. Each workspace gets its own isolated memory space.
### Using Remote Redis
Want to:
- **Share memories across machines**? Use cloud Redis with the same `REDIS_URL` or Cloud Valkey with the same host/port
- **No local install**? Use Upstash, Redis Cloud, or Railway (free tiers available) - see also Valkey cloud instances
- **Team collaboration**? Share Redis URL (or valkey host/port) and workspace path with your team
See [Configuration](#configuration) section for cloud Redis setup.
### Organizational Shared Memory
**Recall enables teams to build collective knowledge** that all Claude instances can access. Perfect for:
**🏢 Organization-wide learning:**
- Share coding standards, architecture decisions, and best practices across the entire team
- Build a living knowledge base that grows with every conversation
- New team members instantly access organizational context and conventions
**👥 Team collaboration:**
- Multiple developers using Claude can contribute to and benefit from shared memories
- Consistent answers to "how do we do X?" across all team members
- Preserve institutional knowledge even as team composition changes
**🔄 Cross-project patterns:**
- Share common patterns and solutions across different projects
- Build reusable memory templates for similar workflows
- Reduce repetitive explanations of organizational context
**Setup for shared organizational memory:**
1. **Deploy shared instance:**
***a) Redis ***
```bash
# Use any cloud Redis service (Upstash, Redis Cloud, etc.)
# Or deploy your own Redis server
```
***b) Valkey ***
```bash
# Use any cloud Valkey service (Elasticache, Memorystore for valkey, etc.)
# Or deploy your own Valkey server
```
2. **Share Connection information with team:**
***a) Redis ***
```json
{
"env": {
"REDIS_URL": "rediss://your-org-redis.com:6379"
}
}
```
***b) Valkey ***
```json
{
"env": {
"BACKEND_TYPE":"valkey",
"VALKEY_HOST":"valkey-remote-host",
"VALKEY_PORT":6379
}
}
```
3. **Define shared workspace path:**
- Option A: Use a fixed workspace path for org-wide memories
- Option B: Wait for v1.3.0 global memories feature for automatic sharing
- Option C: Use project-based isolation but share Redis/Valkey for cross-project search
**Example workflow:**
```
Developer A: "Remember: Our API rate limit is 1000 requests/minute"
[Stored in shared Redis]
Developer B: "What's our API rate limit?"
[Claude retrieves from shared memory]
"Your API rate limit is 1000 requests/minute"
```
**Security considerations:**
- Use Redis authentication and TLS (rediss://) for sensitive data
- Build valkey with TLS support(https://valkey.io/topics/encryption/)
- Consider separate Redis/Valkey databases for different teams/projects
- Implement access controls at the Redis/Valkey level
- Audit memory contents periodically for sensitive information
See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for future plans on enhanced organizational memory features.
### Global Memories (v1.3+)
**Cross-workspace memory sharing** enables memories that work across all workspaces. Perfect for:
- Personal preferences and coding standards
- Team conventions and organizational knowledge
- Shared patterns and solutions
**Workspace Modes:**
- **`isolated`** (default) - Workspace-only memories, no cross-workspace access
- **`global`** - All memories shared globally, no workspace isolation
- **`hybrid`** - Both workspace-specific AND global memories (best of both worlds)
**Configure workspace mode:**
```json
{
"env": {
"WORKSPACE_MODE": "hybrid"
}
}
```
**Create global memories:**
```
"Remember globally: I prefer TypeScript strict mode for all projects"
```
Claude stores with `is_global: true`, accessible across all workspaces.
**Convert existing memories:**
```
"Convert this memory to global: [memory_id]"
```
**Browse global memories:**
- Use `memory://global/recent` resource
- Use `memory://global/search?q=query` for semantic search
- Global resources only work in `global` or `hybrid` modes
See [WORKSPACE_MODES.md](WORKSPACE_MODES.md) for detailed documentation.
---
## Advanced Features (v1.2)
### TTL (Temporary Memories)
Store memories that auto-expire:
```
"Remember for the next hour: API is in maintenance mode"
```
Claude will add `ttl_seconds: 3600` and Redis automatically removes it after 1 hour.
**Use cases:**
- Temporary debugging notes
- Session-specific context
- Time-sensitive reminders
### Export/Import
**Backup your memories:**
```
"Export all important memories to JSON"
```
**Restore or migrate:**
```
"Import these memories: [paste JSON]"
```
**Use cases:**
- Regular backups
- Move memories between workspaces
- Share knowledge bases with team
- Archive old projects
### Duplicate Detection
**Find similar memories:**
```
"Find duplicate memories with similarity above 90%"
```
**Auto-merge duplicates:**
```
"Find and merge duplicate memories automatically"
```
**Use cases:**
- Clean up redundant memories
- Consolidate related information
- Optimize memory storage
### Analytics Dashboard
**See usage patterns:**
```
"Show me memory analytics"
```
Get insights on:
- Memory trends (24h, 7d, 30d)
- Most active types
- Top tags
- Importance distribution
- Daily activity breakdown
---
## Examples
### Example 1: Project Setup
```
You: "Remember: This project uses Prisma for database, tRPC for API, and Next.js for frontend"
Claude: [Stores 3 memories with type 'code_pattern']
✓ Stored: Prisma for database (importance: 8)
✓ Stored: tRPC for API (importance: 8)
✓ Stored: Next.js for frontend (importance: 8)
You (later): "What's our tech stack?"
Claude: [Retrieves memories]
"Your project uses:
- Prisma for database
- tRPC for API
- Next.js for frontend"
```
### Example 2: Code Patterns
```
You: "Store this error handling pattern we use:
try { ... } catch (error) { logger.error(...); throw new AppError(...) }"
Claude: [Stores as 'code_pattern', importance: 9]
✓ Stored: Standard error handling pattern
You (in new file): "Add error handling here"
Claude: [Recalls pattern]
"I'll use your standard error handling pattern with logger and AppError..."
```
### Example 3: Session Organization
```
You: "We just finished refactoring auth. Summarize and save this session."
Claude: [Creates session with all relevant memories]
✓ Session created: "Auth Refactoring - 2025-01-15"
✓ 8 memories captured
✓ Summary: Refactored authentication to use JWT with refresh tokens
You (weeks later): "What did we change in the auth refactoring?"
Claude: [Retrieves session memories]
"In the auth refactoring session, you:
- Switched from sessions to JWT tokens
- Added refresh token rotation
- Implemented secure cookie storage
- Updated middleware for new auth flow"
```
### Example 4: Global Memories (v1.3+)
```
# In project A (with WORKSPACE_MODE=hybrid)
You: "Remember globally: I prefer async/await over .then() in all projects"
Claude: [Stores with is_global: true]
✓ Stored globally: async/await preference (importance: 9)
# Switch to project B
You: "What are my coding preferences?"
Claude: [Retrieves global memories]
"Your global coding preferences include:
- Prefer async/await over .then() in all projects"
# Project-specific memory
You: "Remember for this project only: Use MongoDB with Mongoose"
Claude: [Stores with is_global: false]
✓ Stored: MongoDB with Mongoose (workspace-only, importance: 8)
# Back in project A
You: "What database are we using?"
Claude: [Only sees project A memories, not project B's MongoDB]
"I don't see any database information stored for this workspace."
```
---
## Configuration
### Environment Variables
- **`REDIS_URL`** - Redis connection (default: `redis://localhost:6379`)
- **`BACKEND_TYPE`** - Specifies which backend to use - set to `valkey` for Valkey (default: `redis`) - not needed if using redis.
- **`VALKEY_HOST`** - Valkey host (default: `localhost`)
- **`VALKEY_PORT`** - Valkey port (default: `6379`)
- **`ANTHROPIC_API_KEY`** - Claude API key for analysis and embeddings
- **`WORKSPACE_MODE`** (v1.3+) - Workspace memory mode (default: `isolated`)
- `isolated` - Workspace-only memories, no cross-workspace access
- `global` - All memories shared globally across workspaces
- `hybrid` - Both workspace-specific AND global memories
### Redis Setup Options
**Local Redis (default):**
```bash
redis-server
```
**Custom port:**
```bash
redis-server --port 6380
```
Then set: `REDIS_URL=redis://localhost:6380`
**Remote Redis:**
```json
{
"env": {
"REDIS_URL": "redis://username:password@host:port/db"
}
}
```
**Redis Cloud/AWS ElastiCache:**
```json
{
"env": {
"REDIS_URL": "rediss://your-redis-cloud.com:6379"
}
}
```
### Valkey Setup Options
- see valkey installation options here https://valkey.io/topics/installation/
---
## How It Works
1. **Storage**: Memories stored in Redis/Valkey with workspace isolation
2. **Embeddings**: Hybrid approach using Claude-extracted keywords + trigrams (128-dim vectors)
3. **Search**: Cosine similarity for semantic retrieval
4. **Context**: Auto-injected at conversation start via MCP prompts
5. **Analysis**: Claude Haiku analyzes conversations for memory extraction
### Cost Estimate
Very affordable! Estimated **~$0.20/day** for active development:
- Uses Claude Haiku (cheapest model) for analysis
- Hybrid embeddings reduce API calls
- Redis/Valkey in-memory storage is fast and free
---
## Security Considerations
### Data Sensitivity
Recall stores all conversation context that Claude deems important, which may include:
- **Credentials**: API keys, passwords, tokens mentioned in conversations
- **Code**: Proprietary algorithms, business logic, security implementations
- **Personal Information**: Names, emails, organizational structures
- **Business Secrets**: Strategic decisions, financial data, competitive information
**Critical Security Rules:**
1. **Never use public/shared Redis instances** for sensitive projects
2. **Never share Redis connection strings** in public repositories or documentation
3. **Always use authentication** - Configure Redis with `requirepass`
4. **Always use TLS** for remote connections - Use `rediss://` not `redis://`
5. **Audit regularly** - Review stored memories for inadvertently captured secrets
### Redis Security Configuration
**Local Redis (Development):**
```bash
# Enable authentication
redis-server --requirepass your-strong-password
# Use in config:
# REDIS_URL=redis://:your-strong-password@localhost:6379
```
**Production Redis (Cloud/Remote):**
```json
{
"env": {
"REDIS_URL": "rediss://:password@your-redis-host.com:6379"
}
}
```
**Additional Redis security:**
- Bind to specific IPs: `bind 127.0.0.1 ::1` (local only)
- Disable dangerous commands: `rename-command FLUSHALL ""`
- Use firewall rules to restrict access
- Enable Redis ACLs for fine-grained permissions (Redis 6+)
- Regular backups with encrypted storage
### Valkey Security Configuration
See Valkey security here https://valkey.io/topics/security/, https://valkey.io/topics/acl/, https://valkey.io/topics/persistence/
### Organizational Deployments
When deploying for team/organizational use:
**Infrastructure Security:**
- Deploy Redis/Valkey in private VPC/network
- Use dedicated Redis/Valkey instance (not shared with other services)
- Enable Redis/Valkey encryption at rest
- Implement network segmentation and access controls
- Use VPN or private network access for remote connections
**Access Management:**
- Document who has Redis/Valkey access
- Use separate Redis/Valkey databases for different teams/security levels
- Implement audit logging for Redis/Valkey access
- Regular access reviews and credential rotation
- Consider using Redis/Valkey Enterprise with RBAC
**Data Governance:**
- Define data retention policies
- Implement automated cleanup of old/stale memories
- Create backup and disaster recovery procedures
- Document compliance requirements (GDPR, HIPAA, SOC2, etc.)
- Train users on what not to store in memories
**Example: Multi-team isolation using Redis databases:**
```json
{
"engineering-team": {
"REDIS_URL": "rediss://:password@redis.company.com:6379/0"
},
"product-team": {
"REDIS_URL": "rediss://:password@redis.company.com:6379/1"
},
"exec-team": {
"REDIS_URL": "rediss://:password@redis-exec.company.com:6379/0"
}
}
```
### Incident Response
If you suspect a security breach:
1. **Immediately rotate Redis credentials**
2. **Audit Redis/Valkey access logs** for unauthorized access
3. **Review stored memories** for exposed sensitive data
4. **Flush compromised data** using `export_memories` + selective deletion
5. **Update all team members** with new credentials
6. **Review and strengthen** security controls
### Compliance Considerations
**GDPR (EU):**
- Memories may contain personal data - ensure lawful basis for processing
- Implement data subject access rights (export/delete memories)
- Document data processing activities
- Ensure adequate security measures
**CCPA (California):**
- Disclose data collection and storage practices
- Provide mechanisms for data deletion
- Honor do-not-sell requests
**HIPAA (Healthcare):**
- Do not store PHI (Protected Health Information) in memories
- Use BAA-compliant Redis hosting if healthcare-related
- Implement encryption at rest and in transit
**SOC2/ISO27001:**
- Document security controls and procedures
- Implement access logging and monitoring
- Regular security assessments and audits
### Developer Responsibilities
As a developer using Recall, you must:
✅ **Do:**
- Use secure, authenticated Redis/Valkey instances
- Enable TLS for all remote connections
- Regularly audit stored memories
- Implement proper access controls
- Train your team on security best practices
- Have incident response procedures
- Comply with your organization's security policies
❌ **Don't:**
- Use public Redis/Valkey instances for any sensitive data
- Store credentials or secrets in memories (use environment variables/secret managers instead)
- Share Redis/Valkey connection strings publicly
- Ignore security warnings or skip authentication
- Store regulated data (PII, PHI, PCI) without proper controls
---
## Troubleshooting
### "Cannot connect to Redis"
**Solution 1: Start local Redis**
```bash
redis-server
```
Test connection:
```bash
redis-cli ping
# Should return: PONG
```
**Solution 2: Use cloud Redis (no install needed)**
Sign up for free cloud Redis:
1. **Upstash** (easiest): https://upstash.com
- Create database
- Copy `REDIS_URL` from dashboard
- Update your config with the URL
2. **Redis Cloud**: https://redis.com/try-free
- Free 30MB database
- Get connection string
3. **Railway**: https://railway.app
- Add Redis service
- Use provided connection URL
```json
{
"env": {
"REDIS_URL": "rediss://your-upstash-url.upstash.io:6379"
}
}
```
No local Redis installation required! ✨
### "Tools not showing up in Claude"
**Solution:**
1. Check config file path is correct
2. Verify `ANTHROPIC_API_KEY` is set
3. Restart Claude **completely** (quit and reopen)
4. Check Claude's MCP logs for errors
**Config file locations:**
- **Claude Code**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
### "Memories not persisting"
**Solution:** Check workspace isolation - you may be in a different directory.
Memories are scoped to the working directory where Claude was launched. To see your workspace:
```
"What's my current memory workspace?"
```
### "Out of context" or "Context window full"
**Solution:** Use smart context management:
```
"Analyze our conversation and remember the important parts"
```
This extracts key information before context compaction.
---
## Performance
Typical performance characteristics:
- **Store Memory**: ~200ms (includes embedding generation)
- **Batch Store (10)**: ~500ms
- **Get by ID**: <1ms (Redis in-memory)
- **Recent (50)**: ~10ms
- **Semantic Search (1k memories)**: ~500ms
- **Semantic Search (10k memories)**: ~2s
---
## Version History
- **v1.4.0** (Current) - Memory relationships, knowledge graphs, link related memories
- **v1.3.0** - Global memories, cross-workspace sharing, workspace modes
- **v1.2.0** - TTL support, Export/Import, Consolidation, Analytics
- **v1.1.0** - Smart context management (recall, analyze, summarize)
- **v1.0.0** - Initial release with core memory operations
**[See CHANGELOG.md for detailed changes](CHANGELOG.md)**
---
## Learn More
- **[Feature Documentation](FEATURES_V1.2.md)** - Detailed v1.2 feature guide
- **[Context Management](CONTEXT_MANAGEMENT.md)** - Smart context guide (v1.1)
- **[Changelog](CHANGELOG.md)** - Complete version history
---
## Development
```bash
# Clone and install
git clone <repo-url>
cd mem
npm install
# Build
npm run build
# Development mode (watch)
npm run dev
```
### Testing
Comprehensive test suite available in [tests/](tests/). See [tests/README.md](tests/README.md) for details.
**Quick test run:**
```bash
# Static checks (fast, no dependencies)
./tests/test-v1.5.0-simple.sh
# Runtime tests (requires Redis)
ANTHROPIC_API_KEY="test-key" node tests/test-runtime.js
```
**Testing workflow for releases:**
1. Static checks (file existence, types, build)
2. Runtime tests (server startup, tool availability)
3. Integration tests (full feature testing)
4. Manual tests (Claude Desktop interaction)
See complete workflow in [tests/README.md](tests/README.md#testing-workflow-for-new-releases).
### Project Structure
```
/mem/
├── src/
│ ├── index.ts # Server entry point
│ ├── types.ts # TypeScript types & schemas
│ ├── redis/
│ │ ├── client.ts # Redis connection
│ │ └── memory-store.ts # Storage logic
│ ├── embeddings/
│ │ └── generator.ts # Claude embeddings
│ ├── analysis/
│ │ └── conversation-analyzer.ts # AI analysis
│ ├── tools/
│ │ ├── index.ts # Core tools
│ │ ├── context-tools.ts # Smart context tools
│ │ ├── export-import-tools.ts # Advanced tools
│ │ ├── relationship-tools.ts # Knowledge graphs (v1.4)
│ │ ├── version-tools.ts # Version history (v1.5)
│ │ ├── template-tools.ts # Memory templates (v1.5)
│ │ └── category-tools.ts # Categories (v1.5)
│ ├── resources/
│ │ ├── index.ts # MCP resources
│ │ └── analytics.ts # Analytics resource
│ └── prompts/
│ ├── index.ts # MCP prompts
│ └── formatters.ts # Context formatters
├── tests/ # Test suite
│ ├── README.md # Testing documentation
│ ├── test-v1.5.0-simple.sh # Static checks
│ ├── test-runtime.js # Runtime tests
│ ├── test-v1.5.0.js # Integration tests
│ └── test-v1.5.0-manual.md # Manual checklist
└── dist/ # Built output
```
---
## Support
- **Issues**: Report bugs or request features on GitHub
- **Questions**: Open a discussion for help
- **Documentation**: Check the docs folder for detailed guides
---
## License
MIT - See LICENSE file
---
**Built with ❤️ by José Airosa for Claude users tired of repeating context**
*Powered by: TypeScript, Redis, Anthropic Claude, Model Context Protocol*
