Memory vault

memory-vault gives pi durable memory in an Obsidian-compatible vault. The default is ~/.pi/vault; open that folder as a vault in Obsidian.

MEMORY.md                               index of every memory (regenerated)
Memory/<slug>.md                        global memories: apply in every project
Projects/<project>/<project>.md         project hub: memories + recent recaps
Projects/<project>/Memory/<slug>.md     project memories
Projects/<project>/Recaps/<date>.md     automatic per-turn recaps
Projects/<project>/Workflows/<run>/     workflow runs with `vault: true`
Projects/<project>/.pi-project.json     the canonical root that owns this folder
.pi-index/                              search index, lock, errors.log (hidden from Obsidian)
.trash/                                 forgotten notes (recoverable)

<project> is named after the git root (else the working directory), so every subdirectory of a repository shares one project. Each project folder records the canonical, symlink-resolved root that owns it in Projects/<project>/.pi-project.json. The first root to open a name keeps the plain folder, including a folder written before ownership was recorded; another repository with the same directory name gets <name>-<hash of its canonical path>, so it never recalls or is injected with the first one's recaps and memories. Nothing is moved or deleted (tests/memory-vault-smoke.ts, check 12).

A root reached through a symlink uses the folder its canonical path already owns, whichever path opened it first. A recorded owner is looked up without taking the vault lock. A folder is never taken over because its recorded owner path no longer exists, so a moved repository (or a vault synced from a machine with different checkout paths) starts a <name>-<hash> folder. Its first session then writes a warning to .pi-index/errors.log and the session UI naming the old folder; to keep its history, set "path" in that folder's .pi-project.json to the new canonical path (tests/memory-vault-smoke.ts, check 12).

Two kinds of memory

Automatic: recaps. After each substantive turn (one with tool calls, or a long answer), a small model writes a recap: a title, what was done, the next step, files touched, and decisions. It is appended to Projects/<project>/Recaps/<date>.md. Decisions, preferences and gotchas it flags are promoted to memory notes in that project, deduplicated; a promoted note is never global (tests/memory-vault-smoke.ts, check 5). Trivial turns and subagent children are skipped. The first user prompt of every new session gets the last three recaps as background history, clearly labelled history only and not instructions to resume; the recaps only take the room left over once the pinned and relevant memories are placed, and an oversized recap is dropped whole when a pinned or relevant block needs the room; a lone oversized recap with no pinned and no relevant memory is still truncated with the header and footer kept (tests/memory-vault-smoke.ts, checks 13 and 14).

On request: memory notes. When you say "remember …", the agent uses the memory skill and memory_save. One note per memory, with frontmatter (type: fact | decision | preference | gotcha | reference, scope, tags, dates, source). Saving something with the same or a near-identical title updates the existing note instead of copying it.

Recall

Memories are recalled as a carried note: text added to each request after your messages, through pi's context event. It is never written into the session file, never replayed as a stored user turn, and never put in the system prompt (that would break prompt caching). Compaction drops what was carried, so it is offered again afterwards (tests/memory-vault-smoke.ts). Recall is scoped to the current project plus global memories. It is gated by relevance (BM25 with stopwords and stemming, a minimum score, and two matching terms for multi-word prompts); light stemming makes common inflections meet, so a note saved as "files" is recalled by "file" and vice versa. Each memory is injected at most once per session per unchanged content: a note edited mid-session (via memory_save or /remember) is offered again with its new body, and a session compaction clears the record, so a memory whose recap was summarised away can be recalled again afterwards.

Commands and tools

/remember <text> Save directly (/remember global: … for every project)
/memory Status: vault path, counts, settings
/memory recent Latest recaps for this project
/memory search <q> · /memory forget <id> · /memory migrate Search, forget (to .trash), import memory-local
memory_save, memory_search, memory_forget The agent's tools

Settings

~/.pi/agent/pi-kit/memory.json (environment variables override it):

{
  "vault": "~/.pi/vault",
  "recaps": true,
  "recapModel": "openrouter/deepseek/deepseek-v4.1-flash",
  "autoPromote": true,
  "recallLimit": 3,
  "minScore": 1.5
}

The matching variables are PI_KIT_VAULT, PI_KIT_RECAPS, PI_KIT_RECAP_MODEL, PI_KIT_MEMORY_AUTOPROMOTE, PI_KIT_MEMORY_RECALL_LIMIT and PI_KIT_MEMORY_MIN_SCORE. recapModel should be a cheap, fast model. The default is the session's model.

Secrets in the shapes Luna's shared redaction table knows (tokens, keys, password=-style values) are redacted before anything is written; a shape it does not know is kept, so this is best-effort (see Redaction; tests/memory-vault-smoke.ts, tests/redaction-corpus-smoke.ts). /save --project <p> also writes into the vault's project folder when the vault exists.

The older memory-local store (~/.pi/agent/memory-local/memories.json) is imported automatically once. A malformed or unreadable store is not marked migrated, so a repaired store is imported on a later start. Do not load memory-local next to memory-vault: both register memory_search, and pi keeps only one of them.