Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/memory/README.md

Raw
Rendered preview
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

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": "~/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.

Reference

Commands

Command Purpose
/memory

Setting names

Setting Environment
memory.databasePath PI_MEMORY_DATABASE_PATH
<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.

![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

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/memory` |   |

### Setting names

| Setting | Environment |
| --- | --- |
| `memory.databasePath` | `PI_MEMORY_DATABASE_PATH` |
<!-- config:end -->