Content
# Recall 🧠
**Persistent cross-session memory for Claude and other AI agents. Survives context limits, session restarts, and compaction.**
Store decisions, patterns, and knowledge once — retrieve them automatically across every future conversation. No more repeating yourself. No more losing critical context when the window fills up.
---
## Cloud vs. Self-Hosted
Recall comes in two flavours. Choose the one that fits your situation:
### ☁️ [recallmcp.com](https://recallmcp.com) — Managed SaaS (Recommended for most users)
Zero infrastructure. Sign up, get an API key, add one config block, done.
| What you get | Detail |
|---|---|
| **No Redis required** | Fully managed storage — nothing to install or maintain |
| **Up in 2 minutes** | One config block in Claude Desktop or Claude Code |
| **Team sharing** | One Claude learns something, all others know instantly |
| **Enterprise security** | AES-256-GCM encryption at rest, per-tenant key isolation |
| **Auto-consolidation** | Automatically clusters and merges similar memories |
| **Cross-session workflows** | Named threads that span multiple sessions |
| **7 embedding providers** | Voyage AI, Cohere, OpenAI, Deepseek, Grok, Anthropic, Ollama |
| **Pricing** | Free (500 memories) · Pro $4.99/mo (5K) · Team $9.99/mo (25K) |
```json
{
"mcpServers": {
"recall": {
"url": "https://recallmcp.com/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
```
→ **[Get started at recallmcp.com](https://recallmcp.com)**
---
### 🖥️ This Repository — Self-Hosted (Redis or Valkey)
Run Recall entirely on your own infrastructure. Your data never leaves your servers.
| What you get | Detail |
|---|---|
| **Full data ownership** | Memories stored in your own Redis or Valkey instance |
| **No usage limits** | No memory caps, no subscription required |
| **Air-gapped deployments** | Works fully offline, no external API calls for storage |
| **Bring your own embeddings** | Configure any of 7 providers, or use the Anthropic keyword fallback |
| **Open source** | MIT licensed, fully auditable, fork-friendly |
| **Requires** | Redis ≥ 6 or Valkey, Node.js ≥ 18, your own server/VPS |
Best for: developers who need full control, on-premise requirements, or who already run Redis infrastructure.
---
## ⚠️ 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 persistently. 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
---
## Recall Cloud (Easiest Setup)
**No Redis setup required!** Get started in 2 minutes with the managed cloud service.
### 1. Sign Up
Go to **[recallmcp.com](https://recallmcp.com)** and create a free account.
### 2. Get Your API Key
1. Sign in to your dashboard at [recallmcp.com/dashboard](https://recallmcp.com/dashboard)
2. Go to **API Keys** section
3. Copy your API key (starts with `sk-recall-`)
### 3. Configure Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"recall": {
"url": "https://recallmcp.com/mcp",
"headers": {
"Authorization": "Bearer sk-recall-your-api-key-here"
}
}
}
}
```
> **Note**: Replace `sk-recall-your-api-key-here` with your actual API key from the dashboard.
### 4. Restart Claude Desktop
Quit and reopen Claude Desktop to load the MCP server.
### 5. Test It
Ask Claude:
```text
"Store a memory that I prefer TypeScript for all projects"
```
Then in a new conversation:
```text
"What do you know about my coding preferences?"
```
**It remembers across all your devices!**
---
### Cloud Plans
| Plan | Price | Memories | Features |
| ---------- | -------- | -------- | ----------------------------------------- |
| **Free** | $0/mo | 500 | 1 workspace, basic search |
| **Pro** | $4.99/mo | 5,000 | 3 workspaces, API access, semantic search |
| **Team** | $9.99/mo | 25,000 | Unlimited workspaces, shared memories |
Upgrade anytime at [recallmcp.com/dashboard/billing](https://recallmcp.com/dashboard/billing)
---
### Claude Desktop Custom Connector (OAuth)
**Alternative Setup**: Claude Desktop supports native OAuth connections, so you don't need to edit config files manually.
#### 1. Open Claude Desktop Settings
1. Open Claude Desktop
2. Click on your profile icon → **Settings**
3. Go to **Integrations** → **Custom Connectors**
#### 2. Add Recall Connector
Click **"Add custom connector"** and enter:
| Field | Value |
| -------------------------- | -------------------------------------- |
| **Name** | `Recall` |
| **Remote MCP server URL** | `https://recallmcp.com/mcp` |
| **OAuth Client ID** | `claude-desktop` |
| **OAuth Client Secret** | *(leave empty)* |
#### 3. Authenticate
1. Click **Add** to save the connector
2. Claude Desktop will open a browser window to **recallmcp.com**
3. Sign in with your Google or GitHub account
4. Grant access to connect your Recall account
#### 4. Start Using Recall
Once authenticated, Recall tools are automatically available in Claude Desktop. Ask Claude:
```text
"Store a memory that I prefer dark mode for all applications"
```
Your memories sync across all sessions and devices!
> **Note**: The OAuth connection refreshes automatically. If you see authentication errors, remove and re-add the connector.
---
## Self-Hosted Setup (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. Verify It Works
Ask Claude:
```text
"Store a memory that I prefer using TypeScript for all new projects"
```
Then in a new conversation:
```text
"What do you know about my coding preferences?"
```
**It remembers!**
---
## Claude Code Plugin (One-Liner Install)
Install the Recall plugin for Claude Code with a single command. This gives you enhanced commands, agents, and hooks for working with large files and RLM (Recursive Language Model) features.
### Quick Install
```bash
curl -fsSL https://raw.githubusercontent.com/joseairosa/recall/main/scripts/install-plugin.sh | bash
```
This script will:
- Download the Recall plugin to `~/.claude/plugins/recall-rlm/`
- Configure the MCP server in `~/.claude/settings.json`
- Support updates (re-run the same command to update)
- Create backups before updates
### After Installation
1. **Get your API key** from [recallmcp.com](https://recallmcp.com)
2. **Set the environment variable:**
```bash
export RECALL_API_KEY=sk-recall-your-key-here
# Add to your shell profile for persistence:
echo 'export RECALL_API_KEY=sk-recall-your-key-here' >> ~/.zshrc
```
3. **Restart Claude Code** to load the plugin
### Plugin Features
The plugin adds:
| Feature | Description |
|---------|-------------|
| `/load-context <file>` | Load large files into RLM system for chunk-based analysis |
| `/decompose <chain_id>` | Break tasks into subtasks with strategies (filter, chunk, recursive) |
| `/rlm-status <chain_id>` | Check execution progress and results |
**Hooks (automatic behaviors):**
- Context injection before each prompt
- Large file detection (suggests RLM for >100KB files)
- Session summarization reminders
- Decision storage prompts
### Self-Hosted Configuration
If you prefer Redis locally instead of Recall Cloud, edit `~/.claude/settings.json` after installation:
```json
{
"mcpServers": {
"recall": {
"command": "npx",
"args": ["-y", "@joseairosa/recall"],
"env": {
"REDIS_URL": "redis://localhost:6379"
}
}
}
}
```
### Update & Uninstall
```bash
# Update to latest version
curl -fsSL https://raw.githubusercontent.com/joseairosa/recall/main/scripts/install-plugin.sh | bash
# Uninstall
curl -fsSL https://raw.githubusercontent.com/joseairosa/recall/main/scripts/uninstall-plugin.sh | bash
```
---
## 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*
Connection Info
You Might Also Like
markitdown
MarkItDown-MCP is a lightweight server for converting URIs to Markdown.
markitdown
Python tool for converting files and office documents to Markdown.
firecrawl
Firecrawl MCP Server enables web scraping, crawling, and content extraction.
Filesystem
Node.js MCP Server for filesystem operations with dynamic access control.
TrendRadar
TrendRadar: Your hotspot assistant for real news in just 30 seconds.
mempalace
The highest-scoring AI memory system ever benchmarked. And it's free.