pi-memoria gives Pi one memory shared across every project: instructions that must apply from the first message go in a capped MEMORY.md, everything else in SQLite with FTS5, and past conversations stay searchable through ripgrep. Five tools, local storage only. No embeddings, no network calls, no background model work.

Requirements

• Node.js 22.19+ (uses node:sqlite; earlier baselines 22.19/24.20, maintained suite 26.10.0).
• A Node-based Pi host. The pinned development baseline is 1.0.0, the maintained Pi host. Standalone/Bun builds are not validated with node:sqlite.
• ripgrep (rg), either on PATH or in Pi's managed <agent-dir>/bin/ directory, for session search.

Installation

pi install npm:pi-memoria

This installs the current public npm release. The source version is recorded in package.json; unpublished checkout changes require a local install.

Activate with /reload in an idle session when intended, or a separately approved restart. To uninstall, run pi remove npm:pi-memoria; stored memory remains until you delete its directory.

npm --prefix packages/pi-memoria install --ignore-scripts --legacy-peer-deps --workspaces=false
pi install /absolute/path/to/pi-extensions/packages/pi-memoria

pi -e /absolute/path/to/pi-extensions/packages/pi-memoria/index.ts

How it works

"Start every sentence with beep_boop" belongs in hot memory: even a session starting with "Hello" must obey it. "The user likes apples" belongs in SQLite with tags such as fruit and preferences: a fruit recommendation supplies the retrieval cue.

The model decides what to save and when to search; nothing is extracted automatically. Before saving, it searches for related memories, keeps unchanged facts, and edits existing ones when information changes. SQLite rejects repeated identical adds; differently worded paraphrases depend on the model's judgment.

Hot memory

- [h_0123456789abcdef] [p=90] Start every sentence with beep_boop.

Priority is 0–100 (default 50). The entire file, including IDs and newlines, must fit in 5,000 UTF-16 code units, checked before every write. Content is single-line; CR, LF, U+2028, and U+2029 are rejected.

Duplicate adds reuse the existing bullet and consume no capacity. When space is needed, strictly lower-priority bullets are archived to SQLite first (hot-archive), then the file is atomically replaced; if that cannot free enough room, the write fails with the live file unchanged.

[!WARNING] Prefer the tools for edits. External edits can bypass the cap until the next load, and oversized content is never injected.

Recall

Keyword search uses the supplied terms with prefix matching and English stemming, not automatic terminology rewriting. Save personal shorthand as an ordinary fact containing both forms, for example The user's shorthand piem refers to the pi-extensions monorepo. Searching piem then retrieves that fact; use its meaning for a follow-up search when needed. Session search has no recency or project filter. For "remember when" questions, search sessions and cite the original entries; follow next_offset/next_text_offset, and check warnings and exhausted. A partial or failed search is never proof of absence.

Tools

Tool replies are compact; oversized results spill to a private pi-memoria-result-* file.

Add a fact:

{"content":"The user likes apples.","tags":["fruit","preferences"]}

Add a hot rule:

{"store":"hot","content":"Start every sentence with beep_boop.","priority":90}

Search memories:

{"query":"kubernetes deploy","mode":"all","tags":["infrastructure"]}

Search sessions:

{"query":"deadline","role":"user","after":"2025-03-04","before":"2025-03-05"}

Read a session entry:

{"action":"read","path":"/absolute/path/to/session.jsonl","line":42}

• Add: store is long_term (default) or hot; SQLite accepts tags and source. Identical content is reused with created: false; edits are the only way to change a fact. SQLite limits: 20,000 characters, 30 tags, 2,000-character source.
• Edit/delete: pass an id (m_ for SQLite, h_ for hot) and only the fields to change. expected_revision or hot expected_content catches concurrent writes. Deletion never archives hot bullets or erases sessions.
• Search: memoria_search searches SQLite only; hot h_ entries are injected from MEMORY.md and cannot be searched or read by this tool. mode is any (default), all, phrase, or literal; a miss falls back to a literal scan and reports the mode used. tags match exactly and case-sensitively. Read an SQLite memory with its m_ ID; long content paginates via text_offset.
• Sessions: decoded JSON is searched, including hidden, ignored, and inactive-branch files. Results carry path/line citations. exhausted: true means every accessible root was scanned without errors; warnings mean partial results, never absence.

Configuration

~/.pi/agent/memoria/
├── MEMORY.md
├── memoria.sqlite
└── backups/

Performance

Development

From the monorepo root:

npm --prefix packages/pi-memoria install --ignore-scripts --legacy-peer-deps --workspaces=false
npm run link-host
npm --prefix packages/pi-memoria run verify
npm --prefix packages/pi-memoria run bench

No package lockfile is currently committed, so npm ci is not a fresh-checkout setup command. The shared host-link helper preserves working dependencies and only repairs missing/broken links.

There is no build step: Pi loads index.ts directly. src/database.ts, src/hot-memory.ts, and src/sessions.ts own the storage layers; index.ts wires them to lifecycle events and the tool schemas. Tests use temporary directories, real SQLite FTS5, real rg, concurrent writers, and Pi's extension loader. See AGENTS.md for architecture and contribution rules.

Support and contact

If pi-memoria is useful to you, you can support its development on Ko-fi.