mem0/integrations/pi-agent-plugin

@mem0/pi-agent-plugin

Persistent semantic memory for Pi Agent, powered by Mem0.

This extension gives Pi Agent long-term memory that persists across sessions, projects, and devices. Memories are automatically captured from conversations and can be searched and managed through slash commands and an agent-accessible tool.

Current package version: 0.3.1. Shared redaction and lifecycle utilities come from agent-plugin-core; Pi keeps its own tools and scopes.

Sidekick is available only in the Claude Code plugin.

Features

• Automatic memory capture: learns from every conversation (both user and assistant messages)
• Semantic search: find memories by meaning, not just keywords
• Scoped memory: project, session, or global scope
• Monorepo-aware: uses git root for project detection, consistent app_id across subdirectories
• Confirmation dialogs: destructive commands ask before acting
• 7 slash commands: essential memory management from the command line
• Agent tool: mem0_memory tool lets the agent search and store memories autonomously

Setup

1. Get an API key

Sign up at app.mem0.ai and copy your API key.

2. Install

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

3. Configure

Set the API key as an environment variable:

export MEM0_API_KEY="m0-your-key-here"

Or create a config file at ~/.pi/agent/mem0-config.json:

{
  "apiKey": "m0-your-key-here",
  "userId": "your-username",
  "autoCapture": true,
  "defaultScope": "project",
  "searchThreshold": 0.3
}

Environment variables (MEM0_API_KEY, MEM0_USER_ID) override the config file.

searchThreshold (default 0.3) is the minimum similarity score (0–1) a memory must reach to count as a match for /mem0-search and /mem0-forget. It is passed to the mem0 search API (along with reranking for higher-precision ordering), so a query with no sufficiently similar memory reports no match instead of returning the closest unrelated memories. Raise it to be stricter; lower it if relevant results are missed.

Session handoff

Run /mem0-handoff to save the current session, /mem0-handoff list to find this project’s resources, or /mem0-handoff resume /absolute/path.json to continue from one.

All plugins share local resources in ~/.mem0/handoffs/, preserving supported active context, images, and completed tool outcomes. Resume reads that context as historical evidence. Requires Python 3.10+ as python3; no destination CLI or Mem0 credentials are required. Pi save requires Node.js 22.19+ for its native SDK; list, resume, and memory features remain available on Node.js 20.

The shared engine is fetched from a pinned GitHub commit on first use, verified, and cached across all plugins. Cached use works offline; no transcript is sent to GitHub. See the shared handoff logic for source formats and validation.

Commands

Command	Description
/mem0-remember <text>	Store a memory verbatim (no inference)
/mem0-forget <query>	Search and delete memories (with confirmation)
/mem0-search <query>	Semantic search across memories
/mem0-tour [scope]	Browse all memories grouped by category
/mem0-scope <scope>	Change default scope for this session
/mem0-status	Connection health, identity, and memory count
`/mem0-handoff [save	list

Skills

The plugin includes 6 skills that guide the agent on how to use each capability:

Skill	Purpose
context-loader	Pre-fetch relevant memories at session start
remember	Store facts with category classification
search	Quick semantic search with compact results
forget	Delete memories with confirmation
tour	Full memory walkthrough by category
status	Health check and diagnostics

Memory Scopes

Scope	Filters	Use case
project	user + app_id (git root)	Default. Project-specific knowledge
session	user + app_id + run_id	Recall restricted to memories saved with the current session ID
global	user only	All memories across all your projects

Project scoping uses git rev-parse --show-toplevel to detect the repository root, so all subdirectories within a monorepo share the same memory pool.

Global tool operations require /mem0-scope global or defaultScope: "global" in plugin configuration. A model-supplied scope argument cannot enable cross-project access on its own. Empty or wildcard user, project, and session identities are rejected.

Automatic recall and capture

Before an agent response, the extension searches project memories and injects relevant results. After agent_end, automatic capture sends the user and assistant text supplied by Pi to Mem0 in project scope, regardless of the default scope selected for explicit commands. Captured text is redacted without the former 6,000-character per-message cutoff.

Automatic project writes do not attach run_id. Session-scoped recall applies to memories explicitly saved in session scope; it does not make project memories session-specific or automatically expire them. Recall queries and displayed tool results keep separate size limits.

Memory Categories

Memories are automatically classified into 10 general-purpose categories:

Category	Description
identity	Personal details, background, self-descriptions
preferences	Likes, dislikes, habits, preferred approaches
goals	Objectives, aspirations, targets
projects	Ongoing work, initiatives, areas of focus
decisions	Choices made, rationale, trade-offs
technical	Technical knowledge, tools, configurations
relationships	People, teams, organizations
routines	Recurring patterns, workflows, schedules
lessons	Insights learned, mistakes to avoid
work	Professional context, role, responsibilities

Architecture

pi-agent-plugin/
├── src/
│   ├── entry.ts          # Extension entry point
│   ├── index.ts          # Barrel exports
│   ├── commands.ts       # 6 slash commands
│   ├── prompt.ts         # System prompt injection (MEMORY_POLICY)
│   ├── types.ts          # Shared interfaces and categories
│   ├── telemetry.ts      # PostHog telemetry (batched, PII-safe)
│   ├── config/           # Config loading (~/.pi/agent/mem0-config.json)
│   ├── memory/           # Tool registration, scoping (git root), formatting
│   └── capture/          # Auto-capture from conversations (user + assistant)
├── skills/               # 6 SKILL.md files for Pi Agent
├── tests/                # Vitest unit tests
└── dist/                 # Built output (ESM + DTS)

Development

pnpm install          # Install dependencies
pnpm run typecheck    # Type check
pnpm run test         # Run tests
pnpm run build        # Build (ESM + declarations)

License

Apache-2.0