@tpsdev-ai/pi-flair

Pi extension for Flair memory access — persistent memory from within pi sessions.

Design Decision

Implementation Path: Native pi Extension (Option B)

• MCP clients are NOT first-class in pi — pi's core has no MCP client support. MCP appears only as anthropic-specific beta features in the SDK (BetaMCPToolUseBlock, etc.), not as a generic extension mechanism.
• Option A (wrap flair-mcp) would require:
  • Waiting for pi to support MCP servers natively
  • Deprecating flair-mcp's stdio transport in favor of HTTP-only
  • Splitting maintenance between MCP and pi extensions
• Option B (native extension) wins because:
  • Direct HTTP calls via @tpsdev-ai/flair-client (zero extra dependencies)
  • Full control over tool registration and session lifecycle hooks
  • Parity with flair-mcp features (search, store, bootstrap)
  • Works today — no pi roadmap dependency

Reference: pi extensions docs

Quick Start

Prerequisites

npm install -g @tpsdev-ai/flair
flair init
flair agent add my-agent

Install

pi install npm:@tpsdev-ai/pi-flair

Or project-local:

pi install -l npm:@tpsdev-ai/pi-flair

Configure

pi install writes the package into settings for you. To configure manually, add to ~/.pi/agent/settings.json or .pi/settings.json:

{
  "packages": ["npm:@tpsdev-ai/pi-flair"]
}

Package sources (npm:, git:) belong in packages. The extensions settings key takes local file paths only — an npm: spec there is silently ignored by pi.

Versions <= 0.48.0: older published builds did not declare pi's package manifest (pi.extensions in package.json), so the npm: spec installs but registers no tools — silently (#1346). Upgrade pi-flair, or as a workaround point extensions at the installed file directly:

{
  "extensions": ["~/.pi/agent/npm/node_modules/@tpsdev-ai/pi-flair/dist/index.js"]
}

After installing the extension, configure its required identity in the environment that launches Pi:

export FLAIR_AGENT_ID=my-agent
export FLAIR_URL=http://127.0.0.1:19926
pi

Tools

Configuration Options

Security Notes

Auto-Capture Warning

When FLAIR_AUTO_CAPTURE=true, the handler attempts to store the inspected assistant entry when serialized content exceeds 100 characters and matches no recognized secret pattern. Accepted text is truncated to 4000 characters.

Do not enable FLAIR_AUTO_CAPTURE=true if your sessions may output:

• API keys (sk-, ghp_, pat_, etc.)
• Bearer tokens (Bearer prefix)
• Private keys (-----BEGIN PRIVATE KEY-----, -----BEGIN RSA PRIVATE KEY-----)
• AWS/GCP/Azure credentials
• Any other sensitive data

Auto-capture is best-effort, skips recognized secrets and content of 100 characters or fewer, and truncates text to 4000 characters. For production use, disable auto-capture and store only non-sensitive summaries manually via memory_store.

How It Works

pi (extension) ↔ HTTP ↔ Flair (Harper)

The extension calls Flair's HTTP API directly via @tpsdev-ai/flair-client. The server URL and authentication method (Ed25519 with admin Basic auth fallback) are configurable. Admin Basic auth is used only when no Ed25519 key resolves; the client refuses to send it over plain HTTP to a non-loopback host, because the credentials travel in a request header.

Examples

Semantic Search

// In a pi session:
memory_search(query: "what did I decide about auth flow?", limit: 5)

Store Memory

memory_store(
  content: "PR reviews must include security assessment",
  durability: "persistent"
)

Bootstrap

bootstrap(maxTokens: 4000)

Testing

cd packages/pi-flair
npm run build
# Run tests (TBD)

License

Apache 2.0