pi-mnemoteca

Pi extension for local persistent memory using Mnemoteca. It gives your AI coding agent memory that persists across sessions. It is offline and does not use cloud APIs.

Prerequisites

Install the mnemoteca binary first:

curl -fsSL https://raw.githubusercontent.com/gandazgul/mnemoteca/main/install.sh | sh
mnemoteca setup

See the Mnemoteca README for detailed setup instructions. On first use, Mnemoteca downloads its ML models, approximately 500 MB one time.

Make sure the mnemoteca binary is in your PATH.

Installation

Install from npm:

pi install npm:pi-mnemoteca

Install from a local checkout during development:

pi install ./pi-mnemoteca

Upgrade from pi-mnemosyne

If you already used the old Pi extension, stop Pi agents before you change packages.

1. Migrate CLI data first if needed. Use the Mnemoteca migration guide.
2. Install the new extension at the same scope where the old extension was installed:

   pi install npm:pi-mnemoteca
   

3. Verify that Pi loads the new extension and that memory tools work:

   pi list
   

   Store and recall a harmless test memory if needed.
4. Remove the old package at the matching scope:

   pi remove npm:pi-mnemosyne
   

5. Restart Pi agents.

If your old installation was project-local, run the install and remove commands from that project. If it was user-level, use the same user-level Pi context. Do not keep pi-mnemoteca and pi-mnemosyne active together for normal use.

Windows users must finish this replacement before restarting Pi agents. There is no Windows mnemosyne compatibility shim, alias, copied executable, or renamed executable.

Memory tools

The agent-facing tool names stay stable. They describe memory capabilities, not product branding.

Tool	Purpose
memory_recall	Search project memory.
memory_recall_global	Search global memory.
memory_store	Store a project memory. Set core=true to tag it as core.
memory_store_global	Store a global memory. Set core=true to tag it as core.
memory_delete	Delete a memory by the numeric document ID shown in recall or list output.

Project memory uses a collection name derived from the project directory name. If that name is empty or global, the extension uses default.

The project collection is initialized on session_start. The global collection is created on first use of mnemoteca add -g or the equivalent global store tool.

Session behavior

On session start, the extension:

1. Stores the project working directory.
2. Checks for .mnemoteca-debug.
3. Initializes the project collection with mnemoteca init.
4. Fetches project and global core memories.
5. Caches the core-memory block.

Before each agent start, including after compaction, the extension appends the cached core-memory block and memory-use guidance to the system prompt. Project core memories appear before global core memories. If one core-memory query fails, the other can still appear.

A non-core store does not invalidate the core cache. A core store and any delete operation invalidate it, because the core-tag state can change.

Debug files

Create .mnemoteca-debug in the project directory before session start to enable debug output. The extension writes:

• .mnemoteca-debug.log
• .mnemoteca-debug-prompt.txt

Debug writes are best effort and do not stop agent execution.

Commands taught to the agent

• Use mnemoteca search -f plain [query] and mnemoteca search -g -f plain [query] to search relevant memories.
• After significant decisions, use mnemoteca add "memory content" to save a concise fact. Use mnemoteca add -g "memory content" for cross-project preferences.
• Delete contradicted memories with mnemoteca delete [memory id] after storing the updated memory.
• Mark critical, always-relevant context as core with -t core. You can use repeated tags, such as mnemoteca add "database is sqlite" -t core -t tech-stack.

How it works

session_start
  ├─ save cwd and derive project collection
  ├─ mnemoteca init
  └─ fetch project and global core memories

before_agent_start
  └─ append cached core memories and guidance

memory tools
  ├─ mnemoteca search
  ├─ mnemoteca add [-t core]
  └─ mnemoteca delete

The extension calls the mnemoteca executable with argument arrays. It does not own data storage, select databases, or run migrations.