@pi-unipi/memory

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

Two storage tiers: SQLite + sqlite-vec for vector similarity search, markdown files for human-readable memories 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/
├── global/
│   ├── memory.db              # Global vector DB
│   └── *.md                   # Global memory files
└── <project_name>/
    ├── memory.db              # Project vector DB
    └── *.md                   # Project memory files

Dependencies

• better-sqlite3 — SQLite database
• sqlite-vec — Vector search extension
• js-yaml — YAML frontmatter parsing
• @pi-unipi/core — Shared utilities

License

MIT