pi-portia

library1.1.0jsnpmunverified

Pi-native spatial project memory extension backed by SQLite. Version 1.1.0 (beta). Stores pointers, gotchas, decisions, invariants, purpose, patterns, and plans to help agents re-perceive code faster. Uses project-local SQLite (.pi/portia/portia.sqlite) via better-sqlite3. Provides CLI commands (/portia-status, /portia-search, etc.) and agent tools (portia_sense, portia_record). Follows SemVer for v1.x. Notably does not replace reading source files. Differentiator: lightweight, local-first, inspectable memory layer for Pi agents without external dependencies beyond node >=22 and peer packages (@earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox). No vector search or cloud sync in v1.

storage

npm install pi-portia

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PI-PORTIA

pi-portia

storagejavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import piPortia from 'pi-portia'

✗ const piPortia = require('pi-portia')

Package is ESM-only. CJS require will fail with ERR_REQUIRE_ESM.

createPortiaDB

✓ import { createPortiaDB } from 'pi-portia/db'

✗ import { createPortiaDB } from 'pi-portia'

Named exports are scoped to subpath exports. Check package.json exports map for available paths.

portiaCommands

✓ import { portiaCommands } from 'pi-portia/commands'

Commands are typically registered by Pi plugin system; direct import for testing purposes.

Shows how to install, configure, and use portia with a SQLite database, including recording and searching memories.

// Install: pi install npm:pi-portia // Then in a Pi session: /portia-status // Or via tools (portia_sense, portia_record) in agent code. // Programmatic example (ESM): import { createPortiaDB } from 'pi-portia/db'; import Database from 'better-sqlite3'; const dbPath = '.pi/portia/portia.sqlite'; const db = new Database(dbPath); const portia = createPortiaDB(db, { projectRoot: process.cwd() }); // Record a memory portia.record({ type: 'decision', content: 'Use SQLite for project memory', path: '/src/config.ts', tags: ['architecture'] }); // Search memories const results = portia.search('SQLite'); console.log('Found:', results); db.close();

Debug

Known issues

gotchaPortia uses a project-local SQLite database at .pi/portia/portia.sqlite, which may be excluded from Git by global ignore rules. Ensure the directory exists or the first command will create it.

fix

Run /portia-status or /portia-doctor first to initialize the database. Do not rely on write commands (portia_record) without prior init.

affects: >=1.0.0

breakingv1.1.0 dropping support for Node.js versions below 22. Engines field specifies node >=22.

fix

Upgrade Node.js to version 22 or later. Use nvm or similar to manage versions.

affects: >=1.1.0

deprecatedThe v1.x line may deprecate lowercased command aliases (e.g., /portia-list) in favor of kebab-case (/portia-search). Check CHANGELOG.

fix

Use documented command names: /portia-status, /portia-doctor, /portia-search, /portia-list, etc. Avoid relying on aliases not explicitly documented.

affects: >=1.0.0 <2.0.0

gotchaportia_record is a 'write/proposal' tool – it may be rejected by agent policies. Ensure the agent has write permissions.

fix

Check agent tool permissions or use /portia-sense (read-only) first. If write fails, use CLI command /portia-reindex or /portia-repair as fallback.

affects: >=1.0.0

gotchaSearch uses FTS5 full-text search with ranking. Words must match exactly (no stemming by default). Use wildcard or expansion for partial matches.

fix

For substring search, use query like 'SQLite*' (if FTS5 prefix enabled) or rely on programmatic search functions that apply expansions. Check /portia-doctor for configuration.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

better-sqlite3 is a dependency but may fail to install on some systems (requires native compilation).

fix

Install build tools: on Ubuntu, run 'sudo apt-get install python3 make g++'; on macOS, install Xcode Command Line Tools. Then re-run 'npm install' or 'pi install npm:pi-portia'.

ERR_REQUIRE_ESM

Using require() to load pi-portia in a CommonJS context but the package is ESM-only.

fix

Switch to ESM: add "type": "module" to your package.json or use dynamic import: const piPortia = await import('pi-portia').

portia_record: Command not found

The portia_record tool is only available through the Pi agent tool system, not as a CLI command.

fix

Use CLI command /portia-sense or /portia-doctor instead. For programmatic access, use the portia_sense tool in agent code.

SQLITE_NOTADB: database disk image is malformed

The SQLite database file is corrupted or not a valid database.

fix

Delete the database file at .pi/portia/portia.sqlite and run /portia-doctor to recreate it. If data is important, restore from backup.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite database engine used for storing all memory data

@earendil-works/pi-coding-agentrequiredPeer dependency: provides Pi coding agent integration

@earendil-works/pi-tuirequiredPeer dependency: provides TUI components for commands

typeboxrequiredPeer dependency: runtime type validation for tools/schemas

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/vihu/pi-portia ↗

packagepi-portia ↗

homepagehttps://github.com/vihu/pi-portia#readme ↗