pi-mnemosyne

Pi extension for local persistent memory using Mnemosyne. Gives your AI coding agent memory that persists across sessions — entirely offline, no cloud APIs.

Prerequisites

Install the mnemosyne binary first:

# From source (requires Go 1.21+, GCC, Task)
git clone https://github.com/gandazgul/mnemosyne.git
cd mnemosyne
task install

See the mnemosyne README for detailed setup instructions. On first use, mnemosyne will automatically download its ML models (~500 MB one-time).

Install

# From npm (when published)
pi install npm:pi-mnemosyne

# From local path (for development)
pi install ./pi-mnemosyne

What it does

Core Memories

Core memories are tagged with core and automatically injected into the system prompt at the start of every session (and after compaction). They work like AGENTS.md — always-available context that the agent can reference without explicitly searching.

Use core memories for:

• Project architecture and key conventions
• Important user preferences
• Critical decisions that should never be forgotten

Keep core memories lean — they're injected into every prompt and consume context tokens.

Tools

The extension registers five tools available to the AI agent:

Tool	Description
memory_recall	Search project memory for relevant context and past decisions
memory_recall_global	Search global memory for cross-project preferences
memory_store	Store a project-scoped memory (optionally as core)
memory_store_global	Store a cross-project memory (optionally as core)
memory_delete	Delete an outdated memory by its document ID

Memory Scoping

Scope	Collection	Persists across
Project	<directory-name>	Sessions in the same project
Global	global	All projects
Core (project)	<directory-name> (tagged core)	Sessions + injected into system prompt
Core (global)	global (tagged core)	All projects + injected into system prompt

The project collection is auto-initialized when the extension loads. The global collection is created on first use of memory_store_global.

How it works

Mnemosyne is a local document store with hybrid search:

• Full-text search (SQLite FTS5, BM25 ranking)
• Vector search (sqlite-vec, cosine similarity with snowflake-arctic-embed-m-v1.5)
• Reciprocal Rank Fusion combines both for best results

All ML inference runs locally via ONNX Runtime. Your memories never leave your machine.

Architecture

Session start
  │
  ├─► Auto-init project collection (mnemosyne init)
  └─► Fetch core memories (local + global, tagged "core")
      │
      ▼
  Cached in memory
      │
Each turn (before_agent_start)
  │
  └─► Append cached core memories to system prompt
      (provider-cached, survives compaction)

Agent uses tools
  │
  ├─► memory_recall / memory_recall_global → mnemosyne search
  ├─► memory_store / memory_store_global → mnemosyne add [--tag core]
  │     └─► If core=true → invalidate cache (re-fetched next turn)
  └─► memory_delete → mnemosyne delete
        └─► Invalidate cache (re-fetched next turn)

Development

# Link locally for development
pi install ./pi-mnemosyne

# Check it's installed
pi list

# Start pi — the extension loads automatically
pi

The extension uses TypeScript with pi's built-in jiti loader — no build step required.

License

MIT