pi-engram

Standalone shareable Pi package for Engram persistent memory integration.

It ships a native Pi extension plus a small Engram memory-protocol skill. The recommended install path is npm, with GitHub installs available for pinned or unreleased versions.

Security note: Pi extensions run with your full system permissions. Review extension source before installing packages from any repository.

What it does

• registers native Pi memory tools for Engram
• adds an Engram memory-protocol skill for Pi agents
• tracks Pi session lifecycle events in Engram
• captures user prompts through Pi's input lifecycle event
• attempts to auto-start the Engram backend with engram serve when needed
• keeps startup conservative: it can notify when project memory exists, but it does not auto-inject full memory context
• helps preserve continuity through compaction recovery instructions and summary persistence
• redacts <private>...</private> blocks before sending data to Engram

Install

From npm

pi install npm:pi-engram

Then reload Pi:

/reload

From git

Install the latest main from GitHub:

pi install git:github.com/felipe3dfx/pi-engram

Install a pinned release tag:

pi install git:github.com/felipe3dfx/[email protected]

From Engram TUI/setup flow

Engram's main repository has an active PR for installing the Pi integration through the Engram setup/TUI flow. If you are testing that PR or using an Engram build that includes it, prefer the Engram-managed setup path for the bundled/offline installation experience.

This repository remains the standalone npm/GitHub package for users who want to install the Pi package directly.

Uninstall

List installed packages:

pi list

Remove the package using the same source shown by pi list, for example:

pi remove npm:pi-engram

or for a GitHub install:

pi remove git:github.com/felipe3dfx/pi-engram

Then reload or restart Pi.

Usage

After installation and /reload, Pi agents get native Engram tools and the Engram skill.

Typical prompts:

Remember this architecture decision with Engram.
Search Engram for previous work on this project.
Before we stop, save a session summary.
After compaction, recover context from Engram.

The extension also records lifecycle and prompt metadata automatically where supported by Pi events.

Commands and tools

Slash commands

/engram-status

Shows Engram backend, project, session, binary, auto-start, and last-memory diagnostics. The Engram status line also includes the detected project name, for example 🧠 pi-engram · ready.

/engram-recovery

Shows compaction recovery instructions when automatic compaction summary extraction is unavailable or when you need manual recovery guidance.

Native tools

| Tool | Purpose | |------|---------| | mem_context | Fetch compact project continuity context from Engram. | | mem_search | Search Engram observations with text and optional filters. | | mem_save | Save a durable observation. | | mem_session_summary | Persist an end-of-session or post-compaction summary. | | mem_get_observation | Load one full observation by ID. | | mem_save_prompt | Persist a prompt explicitly when needed. |

Behavior

Backend auto-start

When a memory tool or lifecycle hook needs Engram, the extension checks the local backend health endpoint. If it is not running, it attempts to start:

engram serve

The default binary name is engram. Override it with:

ENGRAM_BIN=/path/to/engram pi

The default port is 7437. Override it with:

ENGRAM_PORT=7437 pi

Startup policy

At session start, the extension may check whether recent project memory exists. If it finds relevant memory and Pi has UI available, it notifies you.

It does not automatically load or inject the full memory context. Ask the agent to call mem_context when you want continuity restored.

Prompt and session capture

The extension uses Pi lifecycle events to:

• register session starts
• save session shutdown metadata
• capture user prompts from the input event
• skip extension-generated input to avoid double capture

Compaction recovery

The extension supports compaction resilience in two ways:

1. session_before_compact tries to inject a FIRST ACTION REQUIRED instruction into compaction instructions when Pi exposes a supported event shape.
2. session_compact tries to persist the compacted summary to Engram.

If summary extraction or persistence is unavailable, run:

/engram-recovery

Then ask the agent to call mem_context manually.

Privacy redaction

Any text wrapped in <private>...</private> is replaced with [REDACTED] before leaving the extension.

Example:

public note <private>secret</private>

becomes:

public note [REDACTED]

Development

The extension entrypoint is:

extensions/engram.ts

The included skill is:

skills/engram/SKILL.md

Run the full release guard locally:

npm run check

This runs TypeScript checks, the Vitest suite, the deterministic runtime harness, and an npm pack dry-run.

Run individual checks when iterating:

npm run typecheck
npm test
npm run test:harness
npm run pack:dry-run

Equivalent direct harness command:

node test/runtime-harness.mjs extensions/engram.ts

The package also has a prepublishOnly guard, so manual npm publish runs the publish checks before uploading.

Relationship to engram setup pi

This repository is the standalone npm/GitHub package for sharing, inspecting, and contributing to the Pi integration.

The Engram monorepo has an active PR for a first-party Pi setup flow via Engram's setup/TUI experience, including the equivalent of:

engram setup pi

That flow materializes and installs a local package from the Engram binary for an embedded/offline experience. This repository does not include that installer wiring; it contains only the standalone Pi package assets used for npm/GitHub distribution.

Troubleshooting

Memory tools cannot auto-start Engram

Verify engram resolves correctly in the environment used to launch Pi:

command -v engram
engram --version

If needed:

ENGRAM_BIN=/absolute/path/to/engram pi

Extension or skill does not appear

Run /reload in Pi after installation, or restart Pi.

Duplicate or stale Pi packages

If Pi reports resource conflicts from stale installs, inspect installed packages:

pi list

Remove stale duplicates with:

pi remove <package-source>

Then reinstall this package.

License

MIT