pi-episodic-memory

Episodic memory for pi — semantic search over all your past conversations. Remember past discussions, decisions, and patterns across sessions and projects.

Inspired by obra/episodic-memory for Claude Code.

What It Does

Every pi session is stored as a .jsonl file. This package indexes those files with local vector embeddings, making them searchable by meaning — not just keywords.

When you (or the LLM) ask "how did we solve X before?", it finds the relevant conversation, even if different words were used.

Features

• Semantic search — finds conversations by meaning using vector similarity
• Text search — exact phrase matching
• Multi-concept AND — search for intersections like ["auth", "middleware", "Express"]
• Cross-project — searches all projects, with optional project filtering
• Date filtering — after / before date constraints
• 100% local — embeddings via Transformers.js, search via SQLite + sqlite-vec. No API calls.
• Automatic indexing — indexes new sessions on startup and shutdown
• Skill file — teaches the LLM when and how to search its memory

Install

# From npm
pi install npm:pi-episodic-memory

# From git
pi install git:github.com/rHedBull/pi-episodic-memory

# Local
pi install /path/to/pi-episodic-memory

What You Get

Tools (for the LLM)

| Tool | Purpose | |------|---------| | episodic_memory_search | Search past conversations semantically | | episodic_memory_show | View the full content of a past session |

Commands (for you)

| Command | Purpose | |---------|---------| | /memory-search <query> | Search from the TUI | | /memory-stats | Show index statistics | | /memory-reindex | Force reindex all sessions |

Skill

The included skill teaches the LLM to search episodic memory when:

• You reference past work ("like we did before")
• An error looks familiar
• Starting similar work to something done previously

How It Works

Session files (~/.pi/agent/sessions/)
  │
  ▼ Parse JSONL → extract user↔assistant messages
  │
  ▼ Chunk into ~4-turn segments with overlap
  │
  ▼ Embed locally (all-MiniLM-L6-v2 via Transformers.js)
  │
  ▼ Store in SQLite + sqlite-vec (~/.pi/agent/episodic-memory/index.db)
  │
  ▼ Search: embed query → nearest neighbors → ranked results

• First run downloads the embedding model (~23MB), then everything is local.
• Incremental — only indexes new/modified files on each startup.
• Chunking — conversations are split into ~4-turn segments with 1-turn overlap for continuity.

Data & Privacy

• All data stays local. No API calls are made.
• Embeddings are generated by a local model (all-MiniLM-L6-v2).
• The index lives at ~/.pi/agent/episodic-memory/index.db.
• To exclude a session from indexing, include <EPISODIC-MEMORY-EXCLUDE/> anywhere in the conversation.

License

MIT