@tpsdev-ai/pi-flair 0.8.0

package/README.md

@@ -0,0 +1,141 @@
+# @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](https://pi.dev/docs/extensions.md)
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+npm install -g @tpsdev-ai/flair
+flair init
+flair agent add my-agent
+```
+
+### Install
+
+```bash
+pi install npm:@tpsdev-ai/pi-flair
+```
+
+Or project-local:
+
+```bash
+pi install -l npm:@tpsdev-ai/pi-flair
+```
+
+### Configure
+
+Add to `~/.pi/agent/settings.json` or `.pi/settings.json`:
+
+```json
+{
+  "extensions": ["npm:@tpsdev-ai/pi-flair"],
+  "packages": ["npm:@tpsdev-ai/pi-flair"]
+}
+```
+
+Or use environment variables:
+
+```bash
+export FLAIR_AGENT_ID=my-agent
+export FLAIR_URL=http://127.0.0.1:9926
+pi
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Search memories by meaning. Understands temporal queries. |
+| `memory_store` | Save memories with type + durability (permanent/persistent/standard/ephemeral). |
+| `bootstrap` | Load session context: soul + memories + predicted context. |
+
+## Configuration Options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FLAIR_AGENT_ID` | *(required)* | Agent identity for memory scoping |
+| `FLAIR_URL` | `http://127.0.0.1:9926` | Flair server URL |
+| `FLAIR_KEY_PATH` | auto-resolved | Path to Ed25519 private key |
+| `FLAIR_MAX_RECALL_RESULTS` | `5` | Max results for memory_search |
+| `FLAIR_MAX_BOOTSTRAP_TOKENS` | `4000` | Max tokens in bootstrap output |
+| `FLAIR_AUTO_RECALL` | `false` | Auto-load bootstrap on session start (opt-in) |
+| `FLAIR_AUTO_CAPTURE` | `false` | Auto-save session context to memory |
+
+## Security Notes
+
+### Auto-Capture Warning
+
+When `FLAIR_AUTO_CAPTURE=true`, all assistant responses are persisted to Flair memory with **ephemeral durability**. **This includes any secrets, credentials, or tokens your LLM may output.**
+
+**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 and uses `dedup: false` to ensure all content is captured. 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`. All memory is stored locally in `~/.flair/` with Ed25519 authentication.
+
+## Examples
+
+### Semantic Search
+
+```ts
+// In a pi session:
+memory_search(query: "what did I decide about auth flow?", limit: 5)
+```
+
+### Store Memory
+
+```ts
+memory_store(
+  content: "PR reviews must include security assessment",
+  durability: "persistent"
+)
+```
+
+### Bootstrap
+
+```ts
+bootstrap(maxTokens: 4000)
+```
+
+## Testing
+
+```bash
+cd packages/pi-flair
+npm run build
+# Run tests (TBD)
+```
+
+## License
+
+[Apache 2.0](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pi Extension for Flair Memory Access
+ *
+ * Adds Flair memory tools to pi sessions:
+ *   - memory_search(agentId, query, limit)  — semantic search
+ *   - memory_store(agentId, content, durability) — save memories
+ *   - bootstrap(agentId, maxTokens) — cold-start context
+ *
+ * Configuration:
+ *   - flair_url (default: http://127.0.0.1:9926)
+ *   - agentId (required, via FLAIR_AGENT_ID env var)
+ *   - max_recall_results (default: 5)
+ *   - max_bootstrap_tokens (default: 4000)
+ *   - auto_capture (default: false) — auto-save session context to memory
+ *   - auto_recall (default: false) — auto-load bootstrap on session start
+ *
+ * Usage:
+ *   1. Install: pi install npm:@tpsdev-ai/pi-flair
+ *   2. Configure in ~/.pi/agent/settings.json or .pi/settings.json:
+ *      {
+ *        "extensions": ["npm:@tpsdev-ai/pi-flair"],
+ *        "flair_url": "http://127.0.0.1:9926",
+ *        "agentId": "my-project"
+ *      }
+ *   3. Or use environment variables:
+ *      export FLAIR_AGENT_ID=my-agent
+ *      export FLAIR_URL=http://127.0.0.1:9926
+ *   4. Restart pi
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { type FlairClientConfig } from "@tpsdev-ai/flair-client";
+interface PluginConfig extends FlairClientConfig {
+    max_recall_results?: number;
+    max_bootstrap_tokens?: number;
+    auto_capture?: boolean;
+    auto_recall?: boolean;
+}
+/**
+ * Classify an error into a user-friendly message.
+ * @param err - The error to classify
+ * @param flairUrl - The Flair server URL for connection error messages
+ */
+export declare function classifyError(err: unknown, flairUrl: string): string;
+export default function (pi: ExtensionAPI): void;
+export declare function manualBootstrap(config: PluginConfig, maxTokens?: number): Promise<string>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAEpF,OAAO,EAA2B,KAAK,iBAAiB,EAAwB,MAAM,yBAAyB,CAAC;AAIhH,UAAU,YAAa,SAAQ,iBAAiB;IAC9C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAkFD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBpE;AAQD,MAAM,CAAC,OAAO,WAAW,EAAE,EAAE,YAAY,QAyMxC;AAID,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,SAAS,SAAO,GACf,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/index.js

@@ -0,0 +1,314 @@
+/**
+ * Pi Extension for Flair Memory Access
+ *
+ * Adds Flair memory tools to pi sessions:
+ *   - memory_search(agentId, query, limit)  — semantic search
+ *   - memory_store(agentId, content, durability) — save memories
+ *   - bootstrap(agentId, maxTokens) — cold-start context
+ *
+ * Configuration:
+ *   - flair_url (default: http://127.0.0.1:9926)
+ *   - agentId (required, via FLAIR_AGENT_ID env var)
+ *   - max_recall_results (default: 5)
+ *   - max_bootstrap_tokens (default: 4000)
+ *   - auto_capture (default: false) — auto-save session context to memory
+ *   - auto_recall (default: false) — auto-load bootstrap on session start
+ *
+ * Usage:
+ *   1. Install: pi install npm:@tpsdev-ai/pi-flair
+ *   2. Configure in ~/.pi/agent/settings.json or .pi/settings.json:
+ *      {
+ *        "extensions": ["npm:@tpsdev-ai/pi-flair"],
+ *        "flair_url": "http://127.0.0.1:9926",
+ *        "agentId": "my-project"
+ *      }
+ *   3. Or use environment variables:
+ *      export FLAIR_AGENT_ID=my-agent
+ *      export FLAIR_URL=http://127.0.0.1:9926
+ *   4. Restart pi
+ */
+import { Type } from "@sinclair/typebox";
+import { FlairClient, FlairError } from "@tpsdev-ai/flair-client";
+// ─── Secret Filtering for Auto-Capture ───────────────────────────────────────
+// Secret patterns to filter from auto-capture
+const SECRET_PATTERNS = [
+    /sk-[a-zA-Z0-9]+/u, // OpenAI keys
+    /ghp_[a-zA-Z0-9_.-]+/u, // GitHub PATs (includes dots for JWT-like tokens)
+    /pat_[a-zA-Z0-9_.-]+/u, // Generic PATs (includes dots for JWT-like tokens)
+    /Bearer [a-zA-Z0-9_.-]+/u, // Bearer tokens (includes dots for JWTs)
+    /-----BEGIN PRIVATE KEY-----/u, // Private keys
+    /-----BEGIN RSA PRIVATE KEY-----/u, // RSA keys
+    /-----BEGIN EC PRIVATE KEY-----/u, // EC keys
+];
+function containsSecrets(text) {
+    return SECRET_PATTERNS.some((pattern) => pattern.test(text));
+}
+// ─── Config Resolution ───────────────────────────────────────────────────────
+function getConfig(pi) {
+    // Try to load from settings
+    // Note: pi doesn't expose settings.json directly in extension API
+    // We rely on environment variables and defaults
+    const flConfig = {
+        url: process.env.FLAIR_URL || "http://127.0.0.1:9926",
+        agentId: process.env.FLAIR_AGENT_ID,
+        keyPath: process.env.FLAIR_KEY_PATH,
+    };
+    return {
+        ...flConfig,
+        max_recall_results: parseInt(process.env.FLAIR_MAX_RECALL_RESULTS || "5", 10),
+        max_bootstrap_tokens: parseInt(process.env.FLAIR_MAX_BOOTSTRAP_TOKENS || "4000", 10),
+        auto_capture: process.env.FLAIR_AUTO_CAPTURE === "true",
+        auto_recall: process.env.FLAIR_AUTO_RECALL === "true", // default false (user must explicitly opt-in)
+    };
+}
+function getAgentId(config, ctx) {
+    if (config.agentId)
+        return config.agentId;
+    // Try to infer from working directory
+    const cwd = ctx.cwd;
+    const lastSlash = cwd.lastIndexOf("/");
+    let agentId;
+    if (lastSlash >= 0) {
+        agentId = cwd.slice(lastSlash + 1);
+    }
+    else {
+        agentId = cwd;
+    }
+    console.warn(`Flair: agentId not configured, falling back to cwd segment "${agentId}". Set FLAIR_AGENT_ID to silence this warning.`);
+    return agentId;
+}
+function createFlairClient(config) {
+    if (!config.agentId) {
+        throw new Error("FLAIR_AGENT_ID is required");
+    }
+    return new FlairClient({
+        agentId: config.agentId,
+        url: config.url || "http://127.0.0.1:9926",
+        keyPath: config.keyPath,
+    });
+}
+// ─── Error Classification ─────────────────────────────────────────────────────
+/**
+ * Classify an error into a user-friendly message.
+ * @param err - The error to classify
+ * @param flairUrl - The Flair server URL for connection error messages
+ */
+export function classifyError(err, flairUrl) {
+    if (err instanceof FlairError) {
+        const { status, body } = err;
+        if (status === 400)
+            return `validation_error: ${body}`;
+        if (status === 401 || status === 403)
+            return `auth_error: ${body}`;
+        if (status === 413)
+            return `payload_too_large: ${body}`;
+        if (status === 429)
+            return "rate_limited — retry after a moment";
+        if (status >= 500)
+            return `server_error (retriable): ${body}`;
+        return `http_error (${status}): ${body}`;
+    }
+    if (err instanceof Error) {
+        if (err.name.includes("Abort") || err.name.includes("Timeout")) {
+            return "timeout — the server took too long. Try shorter content or retry.";
+        }
+        if (err instanceof TypeError && err.message.includes("fetch")) {
+            return `connection_error (retriable): could not reach Flair at ${flairUrl}. Is it running?`;
+        }
+        return `unexpected_error: ${err.message}`;
+    }
+    return `unexpected_error: ${String(err)}`;
+}
+function errorResult(err, flairUrl) {
+    return { content: [{ type: "text", text: classifyError(err, flairUrl) }], details: {}, isError: true };
+}
+// ─── Extension Entry Point ────────────────────────────────────────────────────
+export default function (pi) {
+    const config = getConfig(pi);
+    const flair = createFlairClient(config);
+    // ─── Tools ───────────────────────────────────────────────────────────────────
+    // memory_search tool
+    pi.registerTool({
+        name: "memory_search",
+        label: "Search Flair Memories",
+        description: "Search memories by meaning. Understands temporal queries like 'what happened today'.",
+        promptSnippet: "Search Flair memories for relevant context.",
+        promptGuidelines: [
+            "Use memory_search when you need to recall past conversations, decisions, or lessons from this project.",
+            "Use memory_search when the user asks about 'today', 'recently', or 'previously' in this session.",
+        ],
+        parameters: Type.Object({
+            query: Type.String({ description: "Search query — natural language, semantic matching" }),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 5)" })),
+        }),
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            try {
+                const query = params.query;
+                const limit = params.limit ?? config.max_recall_results;
+                const results = await flair.memory.search(query, { limit });
+                if (results.length === 0) {
+                    return { content: [{ type: "text", text: "No relevant memories found." }], details: {} };
+                }
+                const text = results
+                    .map((r, i) => {
+                    const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
+                    const idStr = r.id ? `id:${r.id}` : "";
+                    const meta = [date, r.type, idStr].filter(Boolean).join(", ");
+                    return `${i + 1}. ${r.content}${meta ? ` (${meta})` : ""}`;
+                })
+                    .join("\n");
+                return { content: [{ type: "text", text }], details: {} };
+            }
+            catch (err) {
+                return errorResult(err, flair.url);
+            }
+        },
+    });
+    // memory_store tool
+    pi.registerTool({
+        name: "memory_store",
+        label: "Store Memory in Flair",
+        description: "Save information to persistent memory. Use for lessons, decisions, preferences, facts.",
+        promptSnippet: "Store memories for future recall.",
+        promptGuidelines: [
+            "Use memory_store to record important decisions, lessons learned, or preferences.",
+            "Use memory_store before finishing a session to capture key insights.",
+        ],
+        parameters: Type.Object({
+            content: Type.String({ description: "What to remember" }),
+            durability: Type.Optional(Type.String({
+                enum: ["permanent", "persistent", "standard", "ephemeral"],
+                description: "permanent — inviolable facts, identity, explicit never-forget (e.g., 'my name is Nathan')\n" +
+                    "persistent — key decisions and lessons to recall weeks later (e.g., 'PR review process')\n" +
+                    "standard — default working memory, recent context (e.g., 'discussed auth flow today')\n" +
+                    "ephemeral — scratch state, auto-expires 72h (e.g., 'currently debugging issue #42')",
+            })),
+            tags: Type.Optional(Type.Array(Type.String(), { description: "Array of tag strings" })),
+        }),
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            try {
+                const content = params.content;
+                const durability = params.durability || "standard";
+                const result = await flair.memory.write(content, {
+                    type: "session",
+                    durability: durability,
+                    tags: params.tags,
+                    dedup: true,
+                    dedupThreshold: 0.95,
+                });
+                // Check if dedup returned an existing memory
+                const agentId = getAgentId(config, ctx);
+                const generatedPrefix = `${agentId}-`;
+                const wasDeduped = result.id && !result.id.startsWith(generatedPrefix);
+                if (wasDeduped) {
+                    return { content: [{ type: "text", text: `Similar memory already exists (id: ${result.id}): ${result.content?.slice(0, 200)}` }], details: {} };
+                }
+                const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
+                const tagStr = params.tags?.length ? params.tags.join(", ") : "none";
+                const text = [
+                    `Memory stored (id: ${result.id})`,
+                    `Preview: ${preview}`,
+                    `Size: ${content.length} chars`,
+                    `Tags: ${tagStr}`,
+                    `Durability: ${durability}`,
+                ].join("\n");
+                return { content: [{ type: "text", text }], details: {} };
+            }
+            catch (err) {
+                return errorResult(err, flair.url);
+            }
+        },
+    });
+    // bootstrap tool
+    pi.registerTool({
+        name: "bootstrap",
+        label: "Bootstrap Flair Context",
+        description: "Get session context: soul + memories + predicted context. Run at session start.",
+        promptSnippet: "Load session context from Flair.",
+        promptGuidelines: [
+            "Call bootstrap at the start of a new session to load relevant past memories.",
+            "Only call bootstrap once per session — it's expensive.",
+        ],
+        parameters: Type.Object({
+            maxTokens: Type.Optional(Type.Number({ description: "Max tokens in output (default 4000)" })),
+        }),
+        async execute(toolCallId, params, signal, onUpdate, ctx) {
+            try {
+                const maxTokens = params.maxTokens ?? config.max_bootstrap_tokens;
+                const result = await flair.bootstrap({ maxTokens });
+                if (!result.context) {
+                    return { content: [{ type: "text", text: "No context available." }], details: {} };
+                }
+                return { content: [{ type: "text", text: result.context }], details: {} };
+            }
+            catch (err) {
+                return errorResult(err, flair.url);
+            }
+        },
+    });
+    // ─── Auto-Recall on Session Start ────────────────────────────────────────────
+    if (config.auto_recall !== false) {
+        pi.on("session_start", async (_event, ctx) => {
+            // In auto_recall mode, inject bootstrap context via before_agent_start
+            // This gives the LLM relevant memories at session start
+            ctx.ui.notify("Flair: loading session context...", "info");
+            try {
+                const maxTokens = config.max_bootstrap_tokens ?? 4000;
+                const result = await flair.bootstrap({ maxTokens });
+                if (result.context) {
+                    // Inject a system message with the context
+                    pi.appendEntry("flair-bootstrap", {
+                        context: result.context,
+                        timestamp: Date.now(),
+                    });
+                    ctx.ui.notify("Flair: context loaded", "info");
+                }
+                else {
+                    ctx.ui.notify("Flair: no context available", "info");
+                }
+            }
+            catch (err) {
+                ctx.ui.notify(`Flair bootstrap failed: ${classifyError(err, flair.url)}`, "error");
+            }
+        });
+    }
+    // ─── Auto-Capture on Turn End (optional) ────────────────────────────────────
+    if (config.auto_capture === true) {
+        pi.on("turn_end", async (_event, ctx) => {
+            // Extract key insights from the turn and store them
+            // This is a simplified version — real implementation would parse the conversation
+            const branch = ctx.sessionManager.getBranch();
+            if (branch.length >= 2) {
+                const lastEntry = branch[branch.length - 2];
+                if (lastEntry.type === "message" && lastEntry.message.role === "assistant" && lastEntry.message.content) {
+                    // Convert to string for storage
+                    const content = JSON.stringify(lastEntry.message.content);
+                    // Filter out content containing secrets
+                    if (containsSecrets(content)) {
+                        console.warn("Auto-capture skipped: potential secrets detected");
+                        return;
+                    }
+                    if (content.length > 100) {
+                        try {
+                            await flair.memory.write(content.slice(0, 4000), {
+                                type: "session",
+                                durability: "ephemeral",
+                                dedup: false,
+                            });
+                        }
+                        catch (err) {
+                            // Silently fail — auto-capture is best-effort
+                            console.warn("Auto-capture failed:", classifyError(err, flair.url));
+                        }
+                    }
+                }
+            }
+        });
+    }
+}
+// ─── Helper for manual bootstrap injection ────────────────────────────────────
+export async function manualBootstrap(config, maxTokens = 4000) {
+    const flair = createFlairClient(config);
+    const result = await flair.bootstrap({ maxTokens });
+    return result.context || "No context available.";
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tpsdev-ai/pi-flair",
+  "version": "0.8.0",
+  "description": "Flair memory extension for pi — persistent memory access from within pi sessions",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@tpsdev-ai/flair-client": "0.8.0",
+    "@sinclair/typebox": "0.34.48"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tpsdev-ai/flair.git",
+    "directory": "packages/pi-flair"
+  },
+  "homepage": "https://tps.dev/#flair",
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "flair",
+    "memory",
+    "semantic-search",
+    "ai",
+    "agent"
+  ],
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "0.73.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0"
+  }
+}