# 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*