Memory

Memory keeps facts, decisions and preferences across sessions, so the agent does not lose them when a session ends.

@pi-unipi/memory · part of UniPi

What it does

• Stores each memory as a Markdown file in ~/.unipi/memory/<project>/<type>/<id>.md. The type is preference, decision, pattern or summary.
• Adds each file to a MemPalace palace for semantic search. Other tools that use MemPalace can read the same palace.
• Shows a memory reminder on the first turn of a session.
• After a task, a background side session can store what it learned. This side session adds nothing to your conversation.
• If MemPalace is not available, memory uses only the Markdown files. If uv is available, the package tries uv tool install mempalace.

The project name is the sanitized base name of the working folder.

Quick start

1. Install UniPi: pi install npm:@pi-unipi/unipi. You can also install this package alone: pi install npm:@pi-unipi/memory.
2. Type /unipi:memory status to see the backend, the daemon and the memory counts.
3. Tell the agent to remember a fact. The agent calls memory_store.

Commands

Command	What it does
/unipi:memory status	Shows the backend, daemon, reader, counts, switches, pending writes and migration state.
/unipi:memory recall on|off	Turns the start reminder on or off for this session only.
/unipi:memory write on|off	Turns the write tools on or off for this session only.
/unipi:memory migrate	Converts v2 memories to the v3 layout. It makes backups first.
/unipi:memory-search <term>	Searches the memories of this project.
/unipi:global-memory-search <term>	Searches the memories of all projects.
/unipi:global-memory-list	Lists the memories of all projects.
/unipi:memory-forget <title>	Deletes a memory by title.
/unipi:memory-process <text>	Tells the agent to find memories in the text and store them.
/unipi:memory-consolidate	Tells the agent to store memories from this session.

Agent tools

Tool	What it does
memory_store	Writes a memory file and adds it to the palace.
memory_search	Searches all projects by default. Use scope: "project" for this project only.
memory_list	Lists the memories of this project.
memory_delete	Deletes a memory by title or ID.

global_memory_search and global_memory_list are aliases for the search and list of all projects.

Settings

Namespace memory. Open it with /unipi:settings.

Key	Default	What it does
recallAtStart	true	Shows the memory reminder on the first turn. Search and list stay available.
write	true	Turns on memory_store, memory_delete and the save pass.
wakeUp	true	Adds mempalace wake-up --wing <project> output to the reminder.
saveMode	side	side uses a background session. reminder asks the agent to save. off stops the save pass.
autoStartDaemon	false	Starts a MemPalace daemon for Pi. While it runs, MemPalace servers in other tools cannot write.
mempalaceAutoUpdate	true	Checks PyPI each day and upgrades MemPalace with uv.

Set enabled to false in ~/.config/mempalace/agent-hooks.json to stop the reminders. Set UNIPI_DEBUG_MEMORY=1 to write a log to ~/.unipi/logs/memory.log.

How it works

Writes go to the MemPalace daemon job queue when a daemon runs. Otherwise, the package runs mempalace mine directly. If both fail, the write waits in a pending file. The next session replays it. Reads go through one read-only mempalace-mcp process for each session.

The read process starts on the first search, not at session start. It stops after 10 minutes without a search, and the next search starts it again (about 1.5 s). One loaded read process uses about 300 MB of RAM.

Every MemPalace process that pi starts gets MALLOC_ARENA_MAX=2. Without it, the daemon grows with each write job and does not give memory back. In a test, it went from 80 MB to 1.3 GB after 160 jobs. With it, the daemon stays at about 380 MB. If you set MALLOC_ARENA_MAX yourself, pi keeps your value. A daemon that runs already keeps its old settings until it restarts.

Upgrade from v2

The migration does not start by itself. When the package finds v2 data, the session card shows a hint.

1. Type /unipi:memory migrate.
2. Read the plan. Accept it.
3. Wait for the footer progress to finish. If Pi stops, the next session continues.

The migration copies the palace to ~/.mempalace/palace.bak-unipi-<ts>. It copies the memory folder to ~/.unipi/memory-v2-backup-<ts>. To go back to v2, put these copies back and install @pi-unipi/unipi@2.

See also

• Compaction
• Settings reference
• Tools reference