## Overview

Add persistent memory to [**Pi Agent**](https://pi.dev/) with `@mem0/pi-agent-plugin`. Your agent forgets everything between sessions. This plugin fixes that by automatically capturing knowledge from conversations, storing it in Mem0’s cloud memory layer, and retrieving relevant context before every response.

## Overview

The plugin provides:

1. **Auto-capture**: Extracts durable facts from both user and assistant messages automatically
2. **Semantic recall**: Retrieves relevant memories via the `mem0_memory` tool before each response
3. **Dream consolidation**: Periodic maintenance: merges duplicates, resolves contradictions, prunes stale entries
4. **Monorepo-aware scoping**: Uses git root for project detection, consistent across subdirectories
5. **Confirmation dialogs**: Destructive commands ask before acting via Pi’s built-in UI
6. **8 skills + 8 commands**: Essential memory management from slash commands and agent-guided workflows

## Prerequisites

1. A Mem0 Platform account and API key:   
   - [Sign up at app.mem0.ai](https://app.mem0.ai/?utm_source=oss&utm_medium=integration-pi-agent)
   - [Get your API key](https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=integration-pi-agent) (starts with `m0-`)
2. Pi Agent installed ( [pi.dev](https://pi.dev/))
3. Your API key added to your shell profile:

zsh
   
   bash

```
   echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
   source ~/.zshrc
   ```

```
   echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
   source ~/.bashrc
   ```

## Installation

``` 
pi install npm:@mem0/pi-agent-plugin
```

That’s it. The extension loads automatically on every Pi session. No config files needed: `MEM0_API_KEY` from your environment is picked up automatically.

Start a new Pi session and run `/mem0-status` to verify the connection. You should see your user ID, detected project, and memory count.

### Optional Configuration

For advanced settings, create `~/.pi/agent/mem0-config.json`:

``` 
{
  "apiKey": "m0-your-key-here",
  "userId": "your-username",
  "autoCapture": true,
  "defaultScope": "project",
  "searchThreshold": 0.3,
  "dream": {
    "enabled": true,
    "auto": true,
    "minHours": 24,
    "minSessions": 5,
    "minMemories": 20
  }
}
```

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `apiKey` | `string` | `$MEM0_API_KEY` | Mem0 API key. Environment variable takes precedence. |
| `userId` | `string` | `$MEM0_USER_ID` or `"default"` | User identity for memory scoping |
| `autoCapture` | `boolean` | `true` | Store facts from conversations automatically |
| `defaultScope` | `string` | `"project"` | Default memory scope: `project`, `session`, or `global` |
| `searchThreshold` | `number` | `0.3` | Minimum similarity score (0–1) a memory must reach to count as a match for `/mem0-search`, `/mem0-forget`, and `/mem0-pin`, enforced on each result’s relevance score. Raise it to be stricter; lower it if relevant results are missed. |
| `dream.enabled` | `boolean` | `true` | Enable dream consolidation |
| `dream.auto` | `boolean` | `true` | Auto-trigger dreams when thresholds are met |
| `dream.minHours` | `number` | `24` | Minimum hours between auto-dreams |
| `dream.minSessions` | `number` | `5` | Minimum sessions before first auto-dream |
| `dream.minMemories` | `number` | `20` | Minimum memories before auto-dream triggers |

## What’s Included

| Component | Description |
| --- | --- |
| `mem0_memory` tool | Agent-callable tool for search, add, get_all, delete, delete_all |
| 8 slash commands | Essential memory management from the command line |
| 8 skills | Guide the agent on how to use each capability |
| Auto-capture | Extracts and stores facts on every `agent_end` event |
| System prompt | Appends memory policy to every agent turn |
| Dream consolidation | Automated memory maintenance with session/time/count gates |

## Agent Tool

The `mem0_memory` tool is registered with Pi and callable by the agent during conversations:

| Action | Required Params | Description |
| --- | --- | --- |
| `search` | `query` | Semantic search across memories |
| `add` | `content` | Store a new memory |
| `get_all` | N/A | List all memories in scope |
| `delete` | `memory_id` | Delete a specific memory |
| `delete_all` | N/A | Delete all memories in scope |

All actions accept an optional `scope` parameter: `project` (default), `session`, or `global`. Tool output is truncated to 200 lines / 50KB to prevent context overflow.

## Commands

| Command | Description |
| --- | --- |
| `/mem0-remember <text>` | Store a memory verbatim (no inference) |
| `/mem0-forget <query>` | Search and delete memories (with confirmation dialog) |
| `/mem0-search <query>` | Semantic search across memories |
| `/mem0-tour [scope]` | Browse all memories grouped by category |
| `/mem0-dream` | Consolidate: merge duplicates, prune stale, resolve contradictions |
| `/mem0-pin <query>` | Pin a memory to protect from dream pruning (preserves memory ID) |
| `/mem0-scope <scope>` | Change default scope for this session (project, session, global) |
| `/mem0-status` | Connection health, identity, and memory count |

## Memory Scopes

Memories are scoped using Mem0’s `user_id`, `app_id`, and `run_id` parameters:

| Scope | Filters | Use Case |
| --- | --- | --- |
| `project` | user_id + app_id (git root) | **Default.** Project-specific knowledge: decisions, architecture, config |
| `session` | user_id + app_id + run_id | Ephemeral context for the current session only |
| `global` | user_id only | All memories across all your projects |

The `app_id` is auto-detected from the git repository root (`git rev-parse --show-toplevel`), so all subdirectories within a monorepo share the same memory pool. Falls back to the working directory name for non-git directories. The `run_id` is derived from Pi’s session file path.

## Dream Consolidation

The plugin includes automated memory maintenance (“dream”) that merges duplicates, resolves contradictions, and prunes stale entries. When enabled, dreams auto-trigger after enough sessions, time, and memories accumulate (configurable via `dream.*` settings). Run `/mem0-dream` to trigger consolidation manually at any time. Pinned memories (via `/mem0-pin`) are protected from pruning.

## Example Workflow

```
# Session 1
You: I prefer dark mode and concise answers.
# Mem0 auto-captures preferences

# Session 2 (days later)
You: What do you know about my preferences?
# Pi retrieves stored memories, no re-explaining needed
```

## Troubleshooting

- **“No API key found”**: Verify `MEM0_API_KEY` is set: `echo $MEM0_API_KEY`. If empty, add it to your shell profile (see Prerequisites)
- **Extension not loading**: Check Pi startup output for errors. Run `pi -e ./src/entry.ts` from the plugin directory for verbose output
- **Memories not capturing**: Verify `autoCapture` is `true` (default). Check `/mem0-status` for connection health
- **Wrong project detected**: The plugin uses the git repository root as `app_id`. If not in a git repo, it falls back to the working directory name. Run `/mem0-status` to see the detected project
- **Dream not triggering**: All three gates must pass (time, sessions, memories). Use `/mem0-dream` to force it manually

**Claude Code Integration**  
Add Mem0 memory to Claude Code

**OpenClaw Integration**  
Add Mem0 memory to OpenClaw agents