memory # memory Give Pi an agent-owned knowledge base: one local SQLite database whose schema the agent designs and evolves with full SQL, journaled end to end. ![Memory demo: the agent stores a fact with SQL, then the viewer audits it](assets/demo.gif) ## Store, audit, recall Ask Pi to remember something and it writes a row: ```text Remember for this project: builds require Node 26. ``` Pi stores the fact with provenance and an observation date, documents the table in `_schema_docs`, and can recall it later with a query. Nothing waits for approval; every call lands in the audit journal instead. The `memory` tool takes raw SQLite: ```json { "sql": "SELECT value FROM facts WHERE entity = 'niri'", "readonly": true } ``` Full DDL and DML: agents create tables, indexes, views, and FTS5 search, then document each table in `_schema_docs` for the next session. Conventions live in a seeded `_guide` table (facts, events, edges, time, context); agents adopt or adapt them. Boundaries that prevent disasters: `ATTACH`, `VACUUM INTO`, and ownership pragmas are blocked, `_journal`/`_stats_samples`/`_health_runs` are readable but not writable, and results beyond 50 rows spill to a temp NDJSON file. Statements are killed at a per-call timeout (default 30s, up to 300s). ## Viewer `/memory` opens an interactive viewer with five tabs: | Tab | Shows | | --- | --- | | Usage | reads/writes per table, never-read zombies, calls per day, error and timeout rates | | Size | bytes per object, data vs index, junk and long-tail clusters | | Health | integrity, WAL, freelist, disk, error rates, with VACUUM and checkpoint actions | | Browse | type and run SQL, inspect rows, write mode behind an explicit confirm | | Journal | every call with actor, SQL, timing; undo restores a pre-write snapshot | Undos and human edits are journaled like everything else. Undo depth follows the journal retention window; the journal keeps the most recent 5000 entries or 90 days, whichever trims first. ## Storage and configuration Works without configuration on Node with bundled `node:sqlite` and FTS5 support. The default DB lives in the OS's local user-data directory under `pi-ext/memory/memory.sqlite`. To choose another location, add this to Pi's user settings: ```json { "memory": { "databasePath": "~/Notes/memory.sqlite" } } ``` `memory.databasePath` accepts an absolute path or `~/path`; empty and relative paths fail instead of silently choosing another DB. Database selection follows environment → trusted project settings → user settings → default. v2 starts fresh: opening a v1 (review-gated) database is refused with instructions rather than migrated. Delete or rename the old file, or point `memory.databasePath` at a new one. Use local disk, not a network share or a live cloud-synced database. Storage is shared plaintext, not an access-control boundary: never store secrets. Back up SQLite consistently, including its WAL when active. Behavioral rules belong in maintained instructions, not in memory. The viewer requires interactive TUI; the `memory` tool works headlessly. [Installation](../../README.md#install). ## Reference ### Commands | Command | Purpose | | --- | --- | | `/memory` | | ### Setting names | Setting | Environment | | --- | --- | | `memory.databasePath` | `PI_MEMORY_DATABASE_PATH` |