shaunguimond.com / pi-codex-memory-extension
Personal extension for pi created based on the Codex project.
Star
Fork 0
Watch
TypeScript 100%
1 1 0
index.ts
README.md
README.md

Codex Memories Extension for Pi #

A persistent session memory system inspired by OpenAI Codex's two-phase memory pipeline.

Overview #

This extension captures reusable knowledge from past sessions and automatically injects it into future agent contexts, helping the AI:

  • Understand user preferences without repetition
  • Avoid known pitfalls and failure modes
  • Reuse proven workflows and shortcuts
  • Save time on similar tasks across sessions

How It Works #

Phase 1: Capture (on agent_end) #

After each agent turn completes, the extension captures session metadata including:

  • Working directory
  • Task description (from first user message)
  • Message counts
  • Optional conversation context preview

This data is stored in ~/.pi/memories/raw_memories.jsonl.

Phase 2: Inject (on before_agent_start) #

Before each new agent turn, the extension loads stored memories and injects them into the system prompt under a "Session Memories" section. The AI can then reference these memories to inform its behavior.

Consolidation (manual via tool) #

Run /consolidate_memories or call the consolidate_memories tool to merge raw memories into structured files:

  • ~/.pi/memories/memory_summary.md — Compact summary for system prompt injection
  • ~/.pi/memories/MEMORY.md — Durable handbook with detailed entries

Storage Layout #

~/.pi/memories/
├── MEMORY.md              # Durable handbook (loaded via grep)
├── memory_summary.md      # Compact summary (injected into system prompt)
├── raw_memories.jsonl     # Captured memories from each session
└── config.json            # Extension configuration

Configuration #

Edit ~/.pi/memories/config.json:

{
  "retentionDays": 30,
  "maxRawMemories": 100,
  "enabled": true,
  "captureContext": false
}
Setting Default Description
retentionDays 30 How long to keep memories before pruning
maxRawMemories 100 Maximum number of raw memory entries to store
enabled true Whether memory capture is active
captureContext false Whether to save conversation context (uses more disk space)

Commands #

  • /memories — Show memory status and recent entries
  • /memories list [type] — List memories, optionally filtered by type
  • /memories prune — Remove stale memories older than retention window
  • /memories consolidate — Trigger Phase 2 consolidation

Custom Tools (callable by LLM) #

Tool Description
list_memories List stored memories with optional filtering
delete_memory Delete a specific memory by ID
consolidate_memories Merge raw memories into MEMORY.md + memory_summary.md
memory_stats Show statistics about stored memories
export_memories Export all memories as formatted markdown

Memory Types #

Type Description Example
preference User preferences, repeated requests, corrections "User prefers patch-only responses without edits"
knowledge Hard-won shortcuts, exact commands/paths, repo facts "Use grep -r instead of rg in this project"
failure_shield Known pitfalls with their fixes "Build fails if env vars not sourced first"
workflow Project-specific conventions that save time "Run tests with npm run test:ci for CI mode"

Inspiration: OpenAI Codex Memory System #

This extension is inspired by Codex's memory architecture which uses:

  1. Phase 1 (Extraction): Parallel LLM calls extract structured memories from recent rollouts using a small model
  2. Phase 2 (Consolidation): A "consolidation agent" merges raw memories into MEMORY.md and memory_summary.md

Key differences in this Pi implementation:

  • Uses Pi's event system (agent_end, before_agent_start) instead of background tasks
  • Stores memories as JSONL for easy programmatic access
  • Leverages Pi's custom tool system for memory management
  • Consolidation is triggered manually rather than automatically

Files Referenced #