pi-memory

pi-memory is an independently maintained memory extension for Pi. Its first release follows a Pi-only, SQLite-first design, providing automatic recall / retain, structured memory, bounded consolidation, and a /memory maintenance entry point.

Installation

Install from a local path:

pi install /Users/jackice/dev/src/github.com/jackice/pi-memory

To enable the built-in hybrid embedding recall path, configure it before starting Pi:

export PI_MEMORY_EMBEDDING_PROVIDER=local-hash

The package entry point is exposed to Pi through the pi.extensions field in package.json.

Current capabilities

• Pi-only: supports Pi only; no compatibility layer for other agents such as OMP, Claude Code, Codex, or Cursor.
• SQLite-first: the default runtime initializes a local SQLite database, schema, FTS, and session state, and wires up recall / retain / consolidation.
• Dual-runtime support: uses the built-in bun:sqlite under Bun (dev/test); when loaded by a Node host it automatically falls back to Node's built-in node:sqlite (requires Node ≥ 22.13, with FTS5 enabled).
• Automatic recall: injects recall results at before_agent_start.
• Cadence retain: retains working memory at turn_end on a cadence, and attempts to extract facts / preferences / instructions / timeline.
• Bounded consolidation: consolidates at session_shutdown, degrading gracefully on LLM rejection or hangs so the main flow never blocks.
• /memory entry point: supports /memory view, /memory stats, /memory diagnose, /memory clear, /memory rebuild.

Degradation behavior

• With no embedding provider configured (default): the recall main path is FTS + structured recall.
• With PI_MEMORY_EMBEDDING_PROVIDER=local-hash configured: the default runtime enables hybrid embedding recall.
• When the embedding provider is unavailable: it degrades back to FTS + structured recall without blocking the Pi main flow.
• When the LLM provider is unavailable:
  • structured extraction falls back to local rule-based extraction;
  • consolidation falls back to a bounded fallback summary;
  • raw working memory is still persisted first, so retain data is never lost because of failed structured extraction.

/memory commands

• /memory view: view a summary of the current project's working / episodic memory.
• /memory stats: view memory count statistics.
• /memory diagnose: view the db path, provider switches, and recall status.
• /memory clear: clear memory data related to the current project/session.
• /memory rebuild: rebuild the FTS index contents.

Explicitly not supported

• Turso / libSQL
• OMP runtime dependencies
• Rust implementation
• Multi-machine sync / external daemon / remote memory service

Development & verification

bun test
bunx tsc --noEmit

To verify the sqlite driver fallback path under a Node host (the actual environment where pi extensions are loaded):

npm run test:node

To run only the documentation install verification test:

bun test test/integration/install-readme.test.ts

Stable exports

• createMemoryRuntime()
• PiMemoryRuntime
• EmbeddingProvider
• LlmProvider
• MemoryRecord
• StructuredMemoryRecord