@badjware/mem0-pi-agent-plugin-oss

Persistent semantic memory for Pi Agent, backed by mem0ai/oss and local SQLite. Local-only fork of @mem0/pi-agent-plugin with the cloud client and plugin telemetry removed.

Differences from upstream @mem0/pi-agent-plugin

• No cloud dependency. Storage is entirely local: mem0ai/oss's built-in SQLite-backed memory vector store plus a SQLite history store under ~/.pi/agent/memories/.
• No plugin telemetry. src/telemetry.ts and every capture call site were deleted.

See PATCH_NOTES.md for the full divergence.

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
• Dream consolidation — merges duplicates, resolves contradictions, prunes stale entries
• Confirmation dialogs — destructive commands ask before acting
• 9 slash commands — essential memory management from the command line
• Agent tool — mem0_memory tool lets the agent search and store memories autonomously

Setup

1. Install

pi install git:github.com/badjware/mem0-pi-agent-plugin-oss

2. Register a local LLM in pi

The plugin uses pi's model registry to find the extraction LLM's credentials and base URL, so the model must already be registered in pi. Follow the instructions in pi's docs to register a LLM provider (e.g., ollama, vllm, lmstudio, etc.) and note the desired provider/model identifier.

3. Configure

Create ~/.pi/agent/mem0-oss-config.json:

{
  "oss": {
    "llm": { "model": "ollama/qwen3.5:4b" }
  },
  "userId": "your-username",
  "autoCapture": true,
  "defaultScope": "project",
  "searchThreshold": 0.2,
  "dream": {
    "enabled": true,
    "auto": true,
    "minHours": 24,
    "minSessions": 5,
    "minMemories": 20
  }
}

oss.llm.model is required. It must be a provider/model identifier already registered in pi. Only ollama, openai-completions-style providers (LM Studio, vLLM, ...), and anthropic-messages providers are supported. MEM0_OSS_LLM_MODEL overrides the config file, and MEM0_USER_ID overrides userId.

Vector store is not configurable for now (mem0's memory vector store, SQLite-backed).

By default the plugin embeds with fastembed (fast-bge-small-en-v1.5, 384 dimensions), bundled and cached locally under ~/.pi/agent/memories/fastembed-cache/. No config is required for this default.

To use an external embedder instead, set oss.embedder in the config file:

{
  "oss": {
    "llm": { "model": "ollama/qwen3.5:4b" },
    "embedder": { "model": "ollama/nomic-embed-text" }
  }
}

oss.embedder.model must use the same provider/model syntax as oss.llm.model; its provider must be registered in pi, the model does not. MEM0_OSS_EMBEDDER_MODEL overrides the config file. Supported providers:

• ollama
• openai-completions

The embedder's identity (provider, model) and its embedding dimension are cached in an embedder metadata file at ~/.pi/agent/memories/mem0-embedder.json. If the embedder doesn't match (e.g. oss.embedder has changed), the plugin refuses to activate. Existing memories must be re-embedded to match the new embedder with /mem0-reindex before the plugin activates.

Categories are preserved via one extra LLM call per capture against the same oss.llm.model, using the same DEFAULT_CUSTOM_CATEGORIES taxonomy as upstream.

searchThreshold (default 0.3) is the minimum similarity score (0–1) a memory must reach to count as a match for /mem0-search, /mem0-forget, and /mem0-pin. It is passed to the mem0 search API, 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.

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-dream	Consolidate — merge duplicates, prune stale, resolve contradictions
/mem0-pin <query>	Pin a memory to protect from dream pruning (preserves ID)
/mem0-scope <scope>	Change default scope for this session
/mem0-status	Runtime health (active/inactive + reason), identity, and memory count
/mem0-reindex	Re-embed all memories with the currently configured embedder (with confirmation), then hot-swap the runtime

Skills

The plugin includes 8 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
dream	Memory consolidation workflow
tour	Full memory walkthrough by category
pin	Protect critical memories from pruning
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	Ephemeral, session-only context
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.

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       # 9 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)
│   └── dream/            # Consolidation state, gating, locking, prompts
├── skills/               # 8 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