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.
Store, audit, recall
Ask Pi to remember something and it writes a row:
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:
{ "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:
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.
<img src="assets/banner.svg" alt="memory" height="70">
# 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.

## 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
<!-- config:start -->
### Commands
| Command | Purpose |
| --- | --- |
| `/memory` | |
### Setting names
| Setting | Environment |
| --- | --- |
| `memory.databasePath` | `PI_MEMORY_DATABASE_PATH` |
<!-- config:end -->