memory

name	memory
description	Persistent cross-session memory management. Store and retrieve user preferences, project decisions, code patterns, and conversation summaries across sessions. Use when you need to remember something important or recall past context.
allowed-tools	["memory_store","memory_search","memory_delete","memory_list","global_memory_search","global_memory_list","read"]

Memory

Persistent cross-session memory for Pi coding agent. Memories survive session restarts, compaction, and context resets.

When to Store Memory

Store memory when you encounter:

Type	Examples	Title Format
Preference	User likes tabs, prefers functional style	style_typescript_prefer_tabs
Decision	Chose PostgreSQL over MySQL, JWT over sessions	db_postgres_chosen_over_mysql
Pattern	How auth is structured, API naming conventions	api_rest_versioning_v2
Summary	Key findings from debugging, research results	perf_slow_query_root_cause

Naming Convention

Format: <most_important>_<less_important>_<lesser>

Rules:

• Use underscores, not hyphens
• Start with category (style, db, auth, api, arch, etc.)
• Be specific: auth_jwt_prefer_refresh_tokens not auth_tokens
• Keep under 60 characters

Good titles:

• style_typescript_strict_mode_always
• db_postgres_use_connection_pooling
• arch_api_versioning_v2_breaking
• perf_cache_redis_for_sessions

Bad titles:

• auth (too vague)
• User prefers tabs (not snake_case)
• auth-jwt-refresh (hyphens, not underscores)

When to Search Memory

Search memory when:

1. User references past work: "Remember when we fixed the auth bug?"
2. Making similar decisions: "What did we decide about database choice?"
3. Setting up new features: "What's the user's coding style?"
4. Debugging recurring issues: "Have we seen this error before?"

How to Use Tools

Store a memory:

memory_store(
  title: "auth_jwt_prefer_refresh_tokens",
  content: "User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d). Always implement token rotation on refresh.",
  tags: ["auth", "jwt", "preferences"],
  type: "preference"
)

Search memories:

memory_search(query: "auth tokens")

List all project memories:

memory_list()

Delete a memory:

memory_delete(title: "auth_jwt_prefer_refresh_tokens")

Search Scope

memory_search searches ALL projects by default. Use scope param to narrow:

Action	Scope	Tool
Store	Always project-scoped	memory_store
Search all projects	Cross-project (default)	memory_search(query) or memory_search(query, scope="all")
Search this project	Current project only	memory_search(query, scope="project")
List all	Cross-project	global_memory_list

All memories are project-scoped. When you store a memory, it belongs to the current project. memory_search searches everything by default — no need to call a separate global search.

Update-First Principle

Always check before creating. Before storing a new memory:

1. Search for similar memories
2. If found and relevant → UPDATE the existing memory
3. If not found → CREATE new memory

This prevents memory duplication and keeps memory clean.

Vector Search (Embeddings)

Memory supports vector similarity search via OpenRouter API.

Setup

1. Run /unipi:memory-settings
2. Add your OpenRouter API key
3. Select embedding model (default: openai/text-embedding-3-small)

How it works

• Embeddings are generated when storing/searching memories
• Search combines vector similarity + fuzzy text matching for best results
• Vector search finds semantically similar memories even without exact keyword matches

Model compatibility

⚠ Different embedding models produce incompatible vectors. If you switch models, existing embeddings won't match new searches. Use /unipi:memory-settings → "Re-embed All Memories" to fix.

No API key?

Falls back to fuzzy text-only search. Still works, just less semantic.

When the user runs /unipi:memory-consolidate or during compaction:

1. Review the session for memory-worthy items
2. For each item:
   • Search for existing similar memory
   • Update if found, create if not
3. Report what was stored/updated

Reading Memory Files

Memory files are stored in ~/.unipi/memory/ as markdown with YAML frontmatter:

---
title: auth_jwt_prefer_refresh_tokens
tags: [auth, jwt, preferences]
project: my-app
created: 2026-04-26T10:00:00Z
updated: 2026-04-26T15:30:00Z
type: preference
---

# Auth: Prefer Refresh Tokens

User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d).
Always implement token rotation on refresh.

You can read these files directly with the read tool for full context.

Anti-Patterns

Don't	Do Instead
Store everything	Only store decisions, preferences, patterns, summaries
Create duplicate memories	Search first, update existing
Use vague titles	Use specific <category>_<detail> format
Store in wrong scope	Project-specific = project scope, universal = global
Forget to update	When context changes, update the memory
Switch embedding models without re-embedding	Re-embed or accept fuzzy-only fallback