@remnic/plugin-pi 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joshua Warren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @remnic/plugin-pi
+
+Remnic memory and context for [Pi Coding Agent](https://pi.dev).
+
+This package is the first-class Remnic extension for Pi. It uses Pi's extension hooks directly, so Remnic can recall context before a model call, observe useful session events after the turn, expose Remnic MCP tools inside Pi, and coordinate Pi compaction with Remnic's long-context memory archive.
+
+## What It Does
+
+- Recalls relevant Remnic context in Pi's `context` hook before an agent turn.
+- Observes Pi user, assistant, and tool messages with `sourceFormat: "pi"`.
+- Flushes Remnic long-context memory before Pi compacts a session.
+- Records Pi compaction checkpoints and token deltas back to Remnic.
+- Registers Remnic MCP tools as Pi tools when daemon authentication is configured.
+- Persists lightweight dedupe state with Pi custom entries so repeated turns are not re-observed.
+
+## Recommended Install
+
+Install through the Remnic CLI. This writes the Pi auto-discovery wrapper, private connector config, and local operator notes into Pi's extension directory.
+
+```bash
+npm install -g @remnic/cli
+remnic daemon start
+remnic connectors install pi
+```
+
+The connector installer writes:
+
+- `~/.pi/agent/extensions/remnic/index.ts`
+- `~/.pi/agent/extensions/remnic/remnic.config.json`
+- `~/.pi/agent/extensions/remnic/README.md`
+
+The generated `remnic.config.json` contains the Remnic daemon URL, namespace, and connector auth token. Remnic writes it with owner-only permissions where the platform supports file modes.
+
+To install the token and connector config without writing the Pi extension files:
+
+```bash
+remnic connectors install pi --config installExtension=false
+```
+
+## Direct Pi Load
+
+You can also load the npm package directly from Pi after configuring the daemon URL and auth token:
+
+```bash
+pi -e npm:@remnic/plugin-pi
+```
+
+For direct loading, provide either `REMNIC_PI_CONFIG` or the default config file at `~/.pi/agent/extensions/remnic/remnic.config.json`.
+
+## Configuration
+
+The extension loads configuration in this order:
+
+1. `REMNIC_PI_CONFIG`
+2. `~/.pi/agent/extensions/remnic/remnic.config.json`
+
+Supported environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `REMNIC_PI_CONFIG` | Path to the Remnic Pi JSON config file |
+| `REMNIC_DAEMON_URL` | Remnic daemon URL when the config file does not set `remnicDaemonUrl` |
+| `REMNIC_PI_AUTH_TOKEN` | Connector token when the config file does not set `authToken` |
+| `PI_CODING_AGENT_DIR` | Pi agent home override used to resolve the extension directory |
+| `PI_AGENT_HOME` | Alternate Pi agent home override |
+| `PI_HOME` | Alternate Pi agent home override |
+
+Supported config keys:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `remnicDaemonUrl` | `http://127.0.0.1:4318` | Remnic HTTP/MCP daemon URL |
+| `authToken` | unset | Connector token generated by `remnic connectors install pi` |
+| `namespace` | unset | Remnic namespace for recall, observe, store, and LCM requests |
+| `recallMode` | `auto` | Recall mode: `auto`, `minimal`, `full`, `graph_mode`, or `no_recall` |
+| `recallTopK` | `8` | Maximum recalled results |
+| `recallBudgetChars` | `12000` | Maximum recalled context injected into Pi |
+| `recallEnabled` | `true` | Enable context-hook recall |
+| `observeEnabled` | `true` | Enable Pi turn observation |
+| `observeSkipExtraction` | `false` | Archive observed messages without extraction |
+| `compactionEnabled` | `true` | Enable LCM flush and checkpoint coordination |
+| `mcpToolsEnabled` | `true` | Register Remnic MCP tools as Pi tools |
+| `statusEnabled` | `true` | Set Pi UI status from daemon health |
+| `requestTimeoutMs` | `5000` | HTTP/MCP request timeout |
+
+Boolean-like strings such as `"false"`, `"0"`, `"no"`, and `"off"` are treated as false.
+
+Example:
+
+```json
+{
+  "remnicDaemonUrl": "http://127.0.0.1:4318",
+  "namespace": "work",
+  "recallMode": "auto",
+  "recallTopK": 8,
+  "recallBudgetChars": 12000,
+  "recallEnabled": true,
+  "observeEnabled": true,
+  "compactionEnabled": true,
+  "mcpToolsEnabled": true,
+  "statusEnabled": true,
+  "requestTimeoutMs": 5000
+}
+```
+
+## Pi Commands
+
+The extension registers these Pi slash commands:
+
+| Command | Description |
+| --- | --- |
+| `/remnic-status` | Check Remnic daemon health |
+| `/remnic-recall <query>` | Recall Remnic context for a query |
+| `/remnic-remember <memory>` | Explicitly store a memory |
+| `/remnic-lcm-search <query>` | Search archived Pi context |
+| `/remnic-why` | Inspect the last recall explanation |
+| `/remnic-compact` | Request Pi compaction with Remnic LCM coordination |
+
+## Security And Boundaries
+
+- Remnic routes Pi traffic with the active Pi session key, working directory, and configured namespace.
+- MCP tool calls strip caller-provided `sessionKey`, `namespace`, and `cwd` before the extension injects trusted values from the Pi runtime.
+- The connector config stores the daemon token locally and is written with `0600` permissions by the Remnic installer.
+- Invalid config values fail closed instead of silently falling back to unsafe defaults.
+- The default daemon URL is local: `http://127.0.0.1:4318`.
+
+## Troubleshooting
+
+If Pi cannot reach Remnic, start the daemon and check the configured URL:
+
+```bash
+remnic daemon start
+remnic status
+```
+
+If commands return `401` or MCP tools do not appear, reinstall the connector so the Pi config receives a fresh token:
+
+```bash
+remnic token generate pi
+remnic connectors install pi --force
+```
+
+If Pi uses a non-default home directory, set one of the supported Pi home variables before installing:
+
+```bash
+PI_CODING_AGENT_DIR=/path/to/pi/agent remnic connectors install pi
+```
+
+## Development
+
+From the Remnic monorepo:
+
+```bash
+pnpm install
+pnpm --filter @remnic/plugin-pi test
+pnpm --filter @remnic/plugin-pi build
+```
+
+The package exports:
+
+- `@remnic/plugin-pi` - Pi extension entrypoint and `createRemnicPiExtension`
+- `@remnic/plugin-pi/publisher` - Remnic connector publisher used by `remnic connectors install pi`
+
+## More
+
+- Full integration guide: https://github.com/joshuaswarren/remnic/blob/main/docs/integration/pi.md
+- Remnic: https://github.com/joshuaswarren/remnic
+- Pi Coding Agent: https://pi.dev

package/dist/chunk-VGPUF4JQ.js

@@ -0,0 +1,26 @@
+// openclaw-engram: Local-first memory plugin
+
+// src/paths.ts
+import os from "os";
+import path from "path";
+import { expandTildePath } from "@remnic/core";
+var REMNIC_PI_EXTENSION_DIR_NAME = "remnic";
+function resolvePiAgentHome(env) {
+  const explicitCodingAgentDir = env.PI_CODING_AGENT_DIR?.trim();
+  if (explicitCodingAgentDir) return path.resolve(expandTildePath(explicitCodingAgentDir));
+  const explicitAgentHome = env.PI_AGENT_HOME?.trim();
+  if (explicitAgentHome) return path.resolve(expandTildePath(explicitAgentHome));
+  const explicitPiHome = env.PI_HOME?.trim();
+  if (explicitPiHome) return path.join(path.resolve(expandTildePath(explicitPiHome)), "agent");
+  return path.join(env.HOME ?? env.USERPROFILE ?? os.homedir(), ".pi", "agent");
+}
+function resolvePiExtensionRoot(env) {
+  return path.join(resolvePiAgentHome(env), "extensions", REMNIC_PI_EXTENSION_DIR_NAME);
+}
+
+export {
+  REMNIC_PI_EXTENSION_DIR_NAME,
+  resolvePiAgentHome,
+  resolvePiExtensionRoot
+};
+//# sourceMappingURL=chunk-VGPUF4JQ.js.map

package/dist/chunk-VGPUF4JQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/paths.ts"],"sourcesContent":["import os from \"node:os\";\nimport path from \"node:path\";\n\nimport { expandTildePath } from \"@remnic/core\";\n\nexport const REMNIC_PI_EXTENSION_DIR_NAME = \"remnic\";\n\nexport function resolvePiAgentHome(env: NodeJS.ProcessEnv): string {\n  const explicitCodingAgentDir = env.PI_CODING_AGENT_DIR?.trim();\n  if (explicitCodingAgentDir) return path.resolve(expandTildePath(explicitCodingAgentDir));\n\n  const explicitAgentHome = env.PI_AGENT_HOME?.trim();\n  if (explicitAgentHome) return path.resolve(expandTildePath(explicitAgentHome));\n\n  const explicitPiHome = env.PI_HOME?.trim();\n  if (explicitPiHome) return path.join(path.resolve(expandTildePath(explicitPiHome)), \"agent\");\n\n  return path.join(env.HOME ?? env.USERPROFILE ?? os.homedir(), \".pi\", \"agent\");\n}\n\nexport function resolvePiExtensionRoot(env: NodeJS.ProcessEnv): string {\n  return path.join(resolvePiAgentHome(env), \"extensions\", REMNIC_PI_EXTENSION_DIR_NAME);\n}\n"],"mappings":";;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AAEjB,SAAS,uBAAuB;AAEzB,IAAM,+BAA+B;AAErC,SAAS,mBAAmB,KAAgC;AACjE,QAAM,yBAAyB,IAAI,qBAAqB,KAAK;AAC7D,MAAI,uBAAwB,QAAO,KAAK,QAAQ,gBAAgB,sBAAsB,CAAC;AAEvF,QAAM,oBAAoB,IAAI,eAAe,KAAK;AAClD,MAAI,kBAAmB,QAAO,KAAK,QAAQ,gBAAgB,iBAAiB,CAAC;AAE7E,QAAM,iBAAiB,IAAI,SAAS,KAAK;AACzC,MAAI,eAAgB,QAAO,KAAK,KAAK,KAAK,QAAQ,gBAAgB,cAAc,CAAC,GAAG,OAAO;AAE3F,SAAO,KAAK,KAAK,IAAI,QAAQ,IAAI,eAAe,GAAG,QAAQ,GAAG,OAAO,OAAO;AAC9E;AAEO,SAAS,uBAAuB,KAAgC;AACrE,SAAO,KAAK,KAAK,mBAAmB,GAAG,GAAG,cAAc,4BAA4B;AACtF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { TSchema } from '@sinclair/typebox';
+
+interface RemnicPiConfig {
+    remnicDaemonUrl: string;
+    authToken?: string;
+    namespace?: string;
+    recallMode: "auto" | "minimal" | "full" | "graph_mode" | "no_recall";
+    recallTopK: number;
+    recallBudgetChars: number;
+    recallEnabled: boolean;
+    observeEnabled: boolean;
+    observeSkipExtraction: boolean;
+    compactionEnabled: boolean;
+    mcpToolsEnabled: boolean;
+    statusEnabled: boolean;
+    requestTimeoutMs: number;
+}
+interface LoadConfigOptions {
+    configPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+
+interface RecallResponse {
+    context?: string;
+    results?: Array<{
+        id?: string;
+        content?: string;
+        score?: number;
+        category?: string;
+    }>;
+    count?: number;
+}
+interface ObserveMessagePart {
+    ordinal?: number;
+    kind: "text" | "tool_call" | "tool_result" | "patch" | "file_read" | "file_write" | "step_start" | "step_finish" | "snapshot" | "retry";
+    payload: Record<string, unknown>;
+    toolName?: string | null;
+    filePath?: string | null;
+    createdAt?: string | null;
+}
+interface ObserveMessage {
+    role: "user" | "assistant";
+    content: string;
+    sourceFormat?: "pi";
+    rawContent?: unknown;
+    parts?: ObserveMessagePart[];
+}
+interface McpTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+declare class RemnicClient {
+    private readonly config;
+    private requestId;
+    constructor(config: RemnicPiConfig);
+    health(): Promise<Record<string, unknown>>;
+    recall(query: string, sessionKey: string, cwd: string): Promise<RecallResponse>;
+    recallExplain(sessionKey: string): Promise<Record<string, unknown>>;
+    observe(sessionKey: string, cwd: string, messages: ObserveMessage[]): Promise<Record<string, unknown>>;
+    storeMemory(content: string, sessionKey: string): Promise<Record<string, unknown>>;
+    lcmSearch(query: string, sessionKey: string, limit?: number): Promise<Record<string, unknown>>;
+    lcmCompactionFlush(sessionKey: string): Promise<Record<string, unknown>>;
+    lcmCompactionRecord(sessionKey: string, tokensBefore: number, tokensAfter: number): Promise<Record<string, unknown>>;
+    contextCheckpoint(sessionKey: string, context: string): Promise<Record<string, unknown>>;
+    mcpListTools(): Promise<McpTool[]>;
+    mcpTool(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private request;
+    private mcpRequest;
+}
+
+declare function textFromMessage(message: unknown): string;
+
+type PiApi = {
+    on(event: string, handler: (event: any, ctx: any) => unknown | Promise<unknown>): void;
+    registerCommand(name: string, options: {
+        description?: string;
+        handler: (args: string, ctx: any) => Promise<void>;
+    }): void;
+    registerTool(tool: Record<string, unknown>): void;
+    appendEntry<T = unknown>(customType: string, data?: T): void;
+};
+interface RemnicPiExtensionOptions extends LoadConfigOptions {
+    config?: RemnicPiConfig;
+}
+declare function createRemnicPiExtension(options?: RemnicPiExtensionOptions): (pi: PiApi) => Promise<void>;
+declare function remnicPiExtension(pi: PiApi): Promise<void>;
+declare function toPiToolParametersSchema(inputSchema: unknown): TSchema;
+declare function stripSessionOwnedSchemaFields(inputSchema: unknown): Record<string, unknown>;
+declare function observeMessages(ctx: any, client: RemnicClient, rawMessages: unknown[], observedHashes: Set<string>, liveObservedReplayKeys?: Map<string, number>): Promise<void>;
+declare function buildCompactionSummary(preparation: any): string;
+
+export { type RemnicPiExtensionOptions, buildCompactionSummary, createRemnicPiExtension, remnicPiExtension as default, observeMessages, stripSessionOwnedSchemaFields, textFromMessage, toPiToolParametersSchema };