pi-memory

Persistent memory for pi. Learns corrections, preferences, and project patterns from sessions and injects them into future conversations.

Features

• Automatic learning — Extracts preferences, project patterns, and corrections from conversations at session end via LLM consolidation
• Context injection — Automatically adds relevant memory into every new session's system prompt
• Corrections stick — Mistakes you correct once become permanent lessons (e.g. "use sed for daily notes, not echo >>")
• Complements session-search — session-search finds what you did, pi-memory remembers what you learned

Install

Recommended: Install pi-total-recall to get the complete context stack — persistent memory, session history search, and local knowledge search in one package:

pi install pi-total-recall

Or install pi-memory standalone:

pi install npm:@samfp/pi-memory

Or add to ~/.pi/agent/settings.json:

{
  "packages": ["npm:@samfp/pi-memory"]
}

Note: Make sure you use the @samfp/ scope. There is an unrelated pi-memory package on npm that will install instead if you omit the scope.

Memory Types

Type	Key prefix	Example
Preferences	pref.*	pref.commit_style → "conventional commits"
Project patterns	project.*	project.rosie.di → "Dagger dependency injection"
Tool preferences	tool.*	tool.sed → "use for daily note insertion"
User identity	user.*	user.timezone → "US/Pacific"
Lessons	(table)	"DON'T: use echo >> for vault notes, use sed"

Tools

Tool	Description
memory_search	Search semantic memory by keyword
memory_remember	Manually store a fact or lesson
memory_forget	Delete a fact or lesson
memory_lessons	List learned corrections
memory_stats	Show memory statistics

Commands

Command	Description
/memory-consolidate	Manually trigger memory extraction from current session

How It Works

1. session_start — Opens the SQLite store, shows memory stats briefly in the status bar
2. before_agent_start — Builds a <memory> context block from stored facts and lessons, appends it to the system prompt
3. agent_end — Collects conversation messages for later consolidation
4. session_shutdown — Runs LLM consolidation (via pi -p --print) to extract structured knowledge, then closes the store

Consolidation

At session end, if there were ≥3 user messages, the extension sends the conversation to an LLM and asks it to extract:

• Preferences — coding style, workflow habits, tool choices
• Project patterns — languages, frameworks, architecture decisions
• Corrections — things you corrected, mistakes to avoid

Only facts with confidence ≥ 0.8 are stored. Lessons are deduplicated using exact match and Jaccard similarity (≥ 0.7 threshold).

Injection

At session start, stored memory is organized into sections (preferences, project context scoped to cwd, tool preferences, lessons, user identity) and injected as a <memory> block in the system prompt. The block is capped at 8KB.

Selective lesson injection — By default, all lessons are injected into every session. When you have many lessons across different domains, this can waste context. Enable selective mode to filter lessons by relevance:

{
  "memory": {
    "lessonInjection": "selective"
  }
}

Add this to ~/.pi/agent/settings.json. In selective mode, lessons are filtered by:

1. Prompt relevance — FTS search against the user's first message
2. Project context — lessons matching the current working directory's project
3. Category inference — keywords in the prompt trigger relevant categories (e.g. "pentest" pulls in bug-bounty lessons, "blog post" pulls in writing lessons)
4. General lessons — always included regardless of prompt

The result is capped at 15 most relevant lessons instead of all of them.

Mode	Behavior
"all" (default)	Every lesson injected into every session
"selective"	Only relevant lessons based on prompt, project, and category

Storage

SQLite database at ~/.pi/memory/memory.db (WAL mode). Three tables:

• semantic — key-value facts with confidence scores
• lessons — learned corrections with dedup
• events — audit log of all memory operations

Project-local storage

To keep a project's memory isolated from your user-global memory, add one of the following to {project}/.pi/settings.json:

{
  // Package-specific — wins over the cascade below.
  "pi-memory": {
    "localPath": ".pi/memory"   // resolves to {project}/.pi/memory/memory.db
  }
}

Or, if installed via pi-total-recall, a single cascade key covers all three bundled packages:

{
  "pi-total-recall": {
    "localPath": ".pi/total-recall"
    // pi-memory             → {project}/.pi/total-recall/memory/memory.db
    // pi-session-search     → {project}/.pi/total-recall/session-search/
    // pi-knowledge-search   → {project}/.pi/total-recall/knowledge-search/
  }
}

Resolution order (highest priority first):

1. pi-memory.localPath in {cwd}/.pi/settings.json
2. pi-total-recall.localPath cascade → {localPath}/memory/memory.db
3. Global default: ~/.pi/memory/memory.db

Existing global installs are unaffected — this is strictly additive.

License

MIT