@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.

Backend: MemPalace — auto-installed via uv on first load, with verified, resumable, incremental migration of existing markdown memories. Detection, ping, and migration run off the startup path, so loading the package never blocks the first prompt.

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 (markdown tier)
├── .mempalace-install           # Cached MemPalace venv detection
├── .mempalace-migrated          # Legacy migration marker (seeds the ledger once)
├── .mempalace-ledger.json       # Record-level sync ledger (project/id -> content hash)
├── .mempalace-ping-verified     # Recent-ping cache (skips the cold-start ping)
├── global/
│   └── *.md                   # Global memory files (durable, human-readable)
└── <project_name>/
    └── *.md                   # Project memory files (durable, human-readable)

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

MemPalace backend

MemPalace is the sole vector backend; the markdown files are the durable, human-readable tier and the migration source. On 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. Marks the backend active immediately, then does everything else off the startup path so time-to-first-input is never blocked: a background task pings the bridge (skipped when recently ping-verified) and runs an incremental catch-up.
3. Catch-up is driven by a record-level ledger (~/.unipi/memory/.mempalace-ledger.json) mapping project/id to the sha256 of the markdown bytes last confirmed in the palace. Only records whose bytes differ from the ledger are upserted, so an ordinary write never triggers a full re-scan. store() updates the ledger only after a confirmed upsert; a pre-existing .mempalace-migrated marker seeds the ledger once. Legacy files are never deleted or mutated.

Records contended by a running MemPalace daemon's mine lock are recorded as deferred (never as failures) and retried with exponential backoff, so the catch-up always converges instead of re-running every boot. When a daemon is reachable and actively mining, the background catch-up stands down for the session rather than fighting the lock.

Memory operations invoke the packaged Python bridge (bridge/mempalace_bridge.py); startup-path work uses the async, non-blocking variant. Both the standalone memory package and the all-in-one umbrella tarball ship and resolve this bridge. 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-ledger.json  # force a full verified catch-up pass 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