pi-mem

Persistent memory extension for pi. Automatically captures what pi does during sessions, compresses observations into searchable memories, and injects relevant context into future sessions.

Features

• Automatic observation capture — hooks into tool_result events to record tool executions
• LLM-powered observation extraction — extracts structured facts, narrative, concepts, and file references from tool output
• Session summaries — compresses observations into searchable memories using checkpoint summarization
• Vector + full-text search — LanceDB-backed semantic and keyword search across all memories
• Context injection — automatically loads relevant past memories at session start
• Memory tools — search, timeline, get_observations, and save_memory tools for the LLM
• Privacy controls — <private> tags to exclude sensitive content
• Project awareness — scopes memories per project (from git remote), supports cross-project search

Installation

pi install npm:pi-mem

Or to try without installing:

pi -e npm:pi-mem

Configuration

Create ~/.pi/agent/pi-mem.json or ~/.pi-mem/config.json (optional — all settings have sensible defaults):

{
  "enabled": true,
  "autoInject": true,
  "maxObservationLength": 4000,
  "summaryModel": "anthropic/claude-haiku-3",
  "indexSize": 10,
  "tokenBudget": 2000,
  "embeddingProvider": "openai",
  "embeddingModel": "text-embedding-3-small",
  "embeddingDims": 1536
}

Setting	Default	Description
enabled	true	Enable/disable the extension
autoInject	true	Automatically inject past memories at session start
maxObservationLength	4000	Max characters per tool output observation
summaryModel	(current model)	Model to use for session summarization
observerModel	(falls back to summaryModel)	Model for per-tool observation extraction
thinkingLevel	(current level)	Thinking level for LLM calls
indexSize	10	Max entries in the project memory index
tokenBudget	2000	Max tokens for injected context
embeddingProvider	(none)	Pi provider name for embeddings. Must support OpenAI-compatible /v1/embeddings
embeddingModel	text-embedding-3-small	Embedding model name
embeddingDims	1536	Embedding vector dimensions (must match the model)

Embedding Setup

For vector/semantic search, configure an embedding provider. The provider must support the OpenAI-compatible /v1/embeddings endpoint. Add the provider name from your ~/.pi/agent/models.json:

{
  "embeddingProvider": "openai",
  "embeddingModel": "text-embedding-3-small",
  "embeddingDims": 1536
}

Without an embedding provider, full-text search still works.

Data Storage

All data is stored in ~/.pi-mem/:

~/.pi-mem/
├── lancedb/                      # Observation store (LanceDB)
└── config.json                   # User preferences (optional)

Commands

• /mem — Show current memory status (project, observation count, vector DB status)

Tools (available to the LLM)

search

Search past observations and summaries with full-text search:

search({ query: "authentication flow" })
search({ query: "authentication", project: "my-app", limit: 5 })

timeline

Get chronological context around a specific observation:

timeline({ anchor: "abc12345" })
timeline({ query: "auth bug", depth_before: 5, depth_after: 5 })

get_observations

Fetch full details for specific observation IDs:

get_observations({ ids: ["abc12345", "def67890"] })

save_memory

Explicitly save important information:

save_memory({
  text: "Decided to use PostgreSQL for ACID transactions",
  title: "Database choice",
  concepts: ["decision", "architecture"]
})

Privacy

Wrap sensitive content in <private> tags in tool output — it will be stripped before observation:

API key is <private>sk-abc123</private>

License

MIT