@pi-unipi/memory

Persistent memory that survives across sessions. Stores facts, preferences, and decisions with semantic vector search, so the agent remembers what you told it last week.

Primary backend: MemPalace — auto-installed via uv on first load, with one-way auto-migration of any existing legacy memories. If MemPalace or uv is unavailable, the package transparently falls back to the bundled SQLite + sqlite-vec store, so memory never hard-fails.

Two storage tiers: MemPalace (or SQLite) for vector similarity search, markdown files for a durable human-readable copy you can edit by hand. Project-scoped memories stay separate per codebase, global memories are accessible everywhere.

Commands

Command	Description
/unipi:memory-process <text>	Analyze text and store extracted memories
/unipi:memory-search <term>	Search project memories
/unipi:memory-consolidate	Consolidate session into memory
/unipi:memory-forget <title>	Delete a memory by title
/unipi:global-memory-process <text>	Analyze text and store to global
/unipi:global-memory-search <term>	Search global memories
/unipi:global-memory-list	List all global memories

Special Triggers

At session start, the agent sees memory titles injected into context. This gives it a summary of what it should remember without loading full memory content.

During compaction (if @pi-unipi/compactor is installed), memories are auto-extracted from the conversation. The memory-consolidate command also triggers this manually.

Memory registers with the info-screen dashboard, showing project memory count, total count, and consolidation count. The footer subscribes to MEMORY_STORED, MEMORY_DELETED, and MEMORYCONSOLIDATED events to display memory stats.

Agent Tools

Tool	Scope	Description
memory_store	Project	Store or update a memory
memory_search	Project	Search memories by query
memory_delete	Project	Delete memory by ID or title
memory_list	Project	List all project memories
global_memory_store	Global	Store or update global memory
global_memory_search	Global	Search global memories
global_memory_list	Global	List all global memories

The agent uses memory_store when it learns something worth remembering — a user preference, a technical decision, a code pattern. memory_search is used to recall relevant context before answering questions.

Memory Format

Memories are markdown files with YAML frontmatter:

---
title: auth_jwt_prefer_refresh_tokens
tags: [auth, jwt, preferences]
project: my-app
created: 2026-04-26T10:00:00Z
updated: 2026-04-26T15:30:00Z
type: preference
---

# Auth: Prefer Refresh Tokens

User prefers short-lived access tokens (15min) with long-lived refresh tokens (30d).
Always implement token rotation on refresh.

Naming Convention

Format: <most_important>_<less_important>_<lesser>

Examples:

• auth_jwt_prefer_refresh_tokens
• db_postgres_use_connection_pooling
• style_typescript_strict_mode_always

Configurables

Memory has no configuration file. Storage paths are fixed:

~/.unipi/memory/                 # UniPi memory root (legacy + markdown tier)
├── .mempalace-install           # Cached MemPalace venv detection
├── .mempalace-migrated          # One-way migration completion flag
├── global/
│   ├── memory.db              # Global vector DB (SQLite fallback)
│   └── *.md                   # Global memory files
└── <project_name>/
    ├── memory.db              # Project vector DB (SQLite fallback)
    └── *.md                   # Project memory files

~/.mempalace/palace/             # MemPalace palace (primary backend)

MemPalace backend

On first load, the memory package:

1. Detects MemPalace; if missing and uv is available, runs uv tool install mempalace once (caches the venv python path in ~/.unipi/memory/.mempalace-install).
2. Pings the bridge to confirm the palace is usable.
3. If ~/.unipi/memory/.mempalace-migrated is absent, performs a one-way read-only migration of every legacy memory (SQLite rows + markdown files across all projects) into MemPalace drawers, then writes the flag. Migration is idempotent (deterministic drawer IDs) and never deletes or mutates legacy files.

Each memory operation invokes a bundled Python bridge (bridge/mempalace_bridge.py) once via spawnSync (~0.5s per call). The first MemPalace use on a machine also downloads the default ONNX embedding model (~80MB, cached at ~/.cache/chroma/onnx_models/).

Forcing re-detection / re-migration

rm ~/.unipi/memory/.mempalace-install    # re-detect MemPalace next session
rm ~/.unipi/memory/.mempalace-migrated   # re-run one-way migration next session

Backend override

Set UNIPI_MEMPALACE_BACKEND to force a MemPalace backend (sqlite_exact, qdrant, pgvector, default chroma).

Embedder identity

MemPalace enforces embedder identity. If a palace was created with a different embedding model, writes are rejected — the package then falls back to SQLite for that session. Use mempalace palace set-embedder intentionally to realign, then remove the install cache to re-detect.

Dependencies

• mempalace (Python, auto-installed via uv) — primary backend
• better-sqlite3 — SQLite fallback database
• sqlite-vec — Vector search extension (fallback)
• js-yaml — YAML frontmatter parsing
• @pi-unipi/core — Shared utilities

License

MIT