pi-total-recall

Complete context stack for pi. One install gives your agent persistent memory, session history, and local knowledge search.

What's included

Layer	Package	What it does
Memory	@samfp/pi-memory	Learns preferences, project patterns, and corrections. Injects relevant facts into every session.
Session history	pi-session-search	Indexes past coding sessions. Search by topic to find previous work, decisions, and debugging context.
Knowledge base	pi-knowledge-search	Indexes local files (markdown, text, docs). Semantic search over your notes, documentation, and vault.

Together, these give pi three layers of context about you:

• What you prefer — coding style, tool choices, project conventions (memory)
• What you've done — past sessions, debugging history, previous decisions (session search)
• What you know — notes, docs, research, reference material (knowledge search)

Install

pi install npm:pi-total-recall

That's it. All three extensions are active immediately.

Requires Node 24+. pi-session-search and pi-knowledge-search use SQLite FTS5 via node:sqlite, which is compiled into Node 24 but not Node 22. On Node 22 you'll see Error: no such table: sessions at startup — upgrade Node and restart pi.

Tools

After installing, your agent gets these tools:

Memory

Tool	Description
memory_search	Search stored facts and preferences
memory_remember	Store a fact or lesson
memory_forget	Remove a stored fact or lesson
memory_lessons	List learned corrections
memory_stats	Show memory statistics

Session History

Tool	Description
session_search	Semantic search over past sessions
session_list	Browse sessions by date, project, or status
session_read	Read the full conversation from a past session

Knowledge Search

Tool	Description
knowledge_search	Semantic search over local files

Configuration

Each component has its own configuration in ~/.pi/agent/settings.json. See the individual package READMEs for details:

Memory

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

Knowledge Search

Point it at your notes directory:

{
  "knowledge-search": {
    "paths": ["~/Documents/Notes"]
  }
}

Session History

Works out of the box — indexes your existing pi sessions automatically.

Project-local storage

By default, all three components write to user-global locations under ~/.pi/ — which is usually what you want, because memory, sessions, and a notes index are normally global across projects.

If you want a project's memory/index to be isolated — e.g. a throwaway prototype, a client repo, or an experimental agent setup — drop a pi-total-recall.localPath key into {project}/.pi/settings.json:

{
  "pi-total-recall": {
    "localPath": ".pi/total-recall"
  }
}

Path resolution: relative paths are resolved against the project root (where you run pi), not the .pi/ directory. So ".pi/total-recall" above resolves to {project}/.pi/total-recall/, and "./data" would resolve to {project}/data/. Use an absolute path (e.g. "/Users/you/shared-index") if you want to pin outside the project.

The key is case-sensitive (localPath, lowercase l). A misspelled key like LocalPath is silently ignored — v1.3.2+ of the bundled packages will log a console.error warning when this happens.

That single key cascades to all three packages:

Package	Cascaded path
@samfp/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/

You can also override any single package independently — package-specific keys win over the cascade:

{
  "pi-total-recall": { "localPath": ".pi/total-recall" },
  "pi-knowledge-search": {
    "localPath": "/some/other/path"   // overrides just this one
  }
}

Resolution order (highest priority first) for every package:

1. Package-specific env vars (KNOWLEDGE_SEARCH_CONFIG, etc.)
2. pi-<package>.localPath in {cwd}/.pi/settings.json
3. pi-total-recall.localPath cascade
4. Global default under ~/.pi/

Caveat: session-search source stays global

pi-session-search relocates only its own config and index — the session source directories (~/.pi/agent/sessions, ~/.pi/agent/sessions-archive) are pi's own files and remain global. That's where pi writes sessions, so making them project-local would point the tool at an empty directory. Use the project filter on session_search and session_list if you want to scope results to one project.

Cleanup

When using pi-total-recall.localPath:

rm -rf {project}/.pi/total-recall   # nukes memory, session-search config+index, knowledge-search config+index

Individual packages

If you only want one or two components, install them directly:

pi install @samfp/pi-memory
pi install pi-session-search
pi install pi-knowledge-search

License

MIT