@sovorn/pi-session-memory 0.1.0

package/README.md

@@ -0,0 +1,224 @@
+# pi-session-memory
+
+[![Pi package](https://img.shields.io/badge/%CF%80-Pi_package-f0b429?style=flat-square)](https://pi.dev/packages/@sovorn/pi-session-memory)
+[![npm](https://img.shields.io/npm/v/@sovorn/pi-session-memory?style=flat-square&logo=npm)](https://www.npmjs.com/package/@sovorn/pi-session-memory)
+[![GitHub](https://img.shields.io/badge/GitHub-sovorn--c%2Fpi--session--memory-181717?style=flat-square&logo=github)](https://github.com/sovorn-c/pi-session-memory)
+
+Session memory for [Pi](https://github.com/earendil-works/pi). It keeps a few short, source-linked notes for the coding session you have open. A local Laya model decides when a note is worth keeping and which note a later turn might need. Your configured Pi model writes the note only after you allow it for that session. If the extension or Laya fails, Pi keeps working with its normal context.
+
+Generation is off by default. Install it, run `/memory status`, and nothing is generated.
+
+## What it does
+
+- Stores observations and reflections in the current Pi session, linked to the original evidence.
+- Uses local Laya decisions to select a small working set of notes for later turns.
+- Lets the model request supporting notes or raw entries with `hydrate_session_memory`.
+- Leaves Pi's history and compaction intact. On memory failures, Pi continues with native context.
+
+This is an experiment, not cross-session search. No usefulness gain has been demonstrated yet. See [known limitations](#known-limitations) before enabling generation.
+
+## Install
+
+This repository is already a Pi package. Pi loads `./src/extension.ts` directly, with no build step. Choose one source below; you do not need to install it more than once.
+
+### From GitHub
+
+```sh
+pi install git:github.com/sovorn-c/pi-session-memory
+```
+
+Pi clones the repository and records the source in your settings. To try it for one run without saving an install:
+
+```sh
+pi -e git:github.com/sovorn-c/pi-session-memory
+```
+
+### npm
+
+Install [`@sovorn/pi-session-memory`](https://www.npmjs.com/package/@sovorn/pi-session-memory) through Pi. The unscoped name belongs to a different project.
+
+```sh
+pi install npm:@sovorn/pi-session-memory
+```
+
+Pi manages the npm download and extension registration. `npm install` alone does not register the extension in Pi. The `pi-package` keyword makes a published package eligible for the [Pi package gallery](https://pi.dev/packages/@sovorn/pi-session-memory).
+
+### From a local checkout
+
+```sh
+git clone https://github.com/sovorn-c/pi-session-memory.git
+pi install /path/to/pi-session-memory
+```
+
+Replace `/path/to/pi-session-memory` with the cloned directory. Pi records the path in `settings.json`; it does not copy the directory. To load only its entry for one run:
+
+```sh
+pi -e /path/to/pi-session-memory/src/extension.ts
+```
+
+After install, start Pi and run `/memory status`. It shows generation, config path, Python command, and token cadence. Installation does not install Python, Laya, or model weights. Complete [Laya setup](#laya-setup) before enabling generation.
+
+## Requirements
+
+You need Pi and Python 3.11. This tree was checked on macOS arm64 with Pi 1.0.2, Node v26.7.0, and Python 3.11.15.
+
+Laya 0.3.7 and its typed-decisions checkpoint are separate prerequisites. The worker checks the exact tested code revision and model weights before loading. See [Laya setup](#laya-setup) for those pins.
+
+## Configure
+
+Optional. With no config file, generation stays off and the other defaults below apply.
+
+The file is `<Pi agent dir>/pi-session-memory/config.json`. The agent directory is usually `~/.pi/agent`. `PI_CODING_AGENT_DIR` overrides it. You create the file yourself. The extension reads it when a session starts and never writes it. A missing file uses the defaults. A malformed file uses the defaults and warns once.
+
+| Key | Type | Default |
+| --- | --- | --- |
+| `generation` | boolean | `false` |
+| `python` | non-empty string, optional | `python3.11` |
+| `observeAfterTokens` | integer >= 1 | `10000` |
+| `reflectAfterTokens` | integer >= 1 | `20000` |
+
+`PI_SESSION_MEMORY_PYTHON` overrides `python`. `PI_SESSION_MEMORY_LAYA_CHECKPOINT` overrides the checkpoint directory. For the Python command, the environment variable wins, then the config value, then `python3.11`.
+
+How many notes can be considered (6, maximum 8) and how long a projected note can be (4000 characters, maximum 6000) are internal limits, not settings. Edit the file, then `/reload` or start Pi again.
+
+Example, still off until you also confirm in the session:
+
+```json
+{
+  "generation": false,
+  "python": "python3.11",
+  "observeAfterTokens": 10000,
+  "reflectAfterTokens": 20000
+}
+```
+
+## Use
+
+`/memory` with no arguments is the same as `/memory status`.
+
+`/memory status` prints whether generation is on, the config path, the Python command, and the cadence. It does not start Laya and does not call your model.
+
+`/memory on` enables generation for this session only. `/memory on` is not consent. The first time this session is about to write a memory, Pi asks you to confirm. Nothing is sent until you confirm.
+
+`/memory off` disables generation for this session and drops a confirmation already stored for it. Neither command writes the config file or the session file.
+
+A new session, a fork, a resume, or `/reload` clears that session switch. You are asked again before the next write.
+
+When a later request needs an earlier note, local Laya may select one. Projected memory reaches the normal Pi provider inside the request Pi was already going to send. The model can call `hydrate_session_memory` to read a reflection, the observation it came from, or the exact linked raw entries. A missing link is reported. A replacement is not invented.
+
+## Disable and remove
+
+`/memory off` turns generation off for the current session. The extension stays loaded.
+
+`pi --no-extensions` disables every extension for that run, including this one if you installed it.
+
+Remove the source you installed:
+
+```sh
+# GitHub install:
+pi remove git:github.com/sovorn-c/pi-session-memory
+
+# npm install:
+pi remove npm:@sovorn/pi-session-memory
+
+# Local checkout:
+pi remove /path/to/pi-session-memory
+```
+
+Remove drops the package source from `settings.json`. Your session files and any Laya cache stay where they are.
+
+## What gets sent
+
+Generation is off by default. A write needs both a switch and an interactive confirmation: `generation: true` in the config, or `/memory on`, and then your answer for that session. `/memory on` is not consent. Pi shows this question:
+
+> Session-derived text and its source entry IDs will be sent to the currently configured Pi model/provider only after a local Laya gate accepts. Laya runs locally. The Pi session remains canonical; generated memories are appended as non-context session entries. Do you allow this for the current session?
+
+There is one provider call site, `modelRegistry.complete`. Decline, and that write does not happen. Projected memory reaches the normal Pi provider as part of a request Pi was already sending. `hydrate_session_memory` returns entries already in the session and does not call the provider.
+
+The extension runs with Pi's permissions. Behavior lives under `src/` and `worker/`. A static scan of `src/` and `worker/` finds no telemetry client and no network client. Recorded checks set `PI_OFFLINE=1`, `PI_TELEMETRY=0`, `HF_HUB_OFFLINE=1`, and `TRANSFORMERS_OFFLINE=1`.
+
+## What one trial showed
+
+One synthetic trial compared a native arm with a memory arm. The native arm ran first. The result was no demonstrated benefit. The keyword oracle did not show a gain. Token usage was not recorded. The model was `openai-codex/gpt-6-luna` at thinking low, with 8 provider calls and 3 Laya decisions.
+
+## Known limitations
+
+- Checked on macOS arm64, English, and one Pi session. There is no cross-session memory.
+- Provider-backed memory formation is not verified on Pi 1.0.2. It was last verified on Pi 0.87.1. Pi 1.0.2 checks so far used generation off, in no-provider runs.
+- In RPC mode the confirmation waits for the client's answer.
+- The first Laya load can take seconds. Laya confidence is uncalibrated for some choices.
+- No build, lint, typecheck, or CI is configured. Laya setup is machine-specific.
+- This is experimental. A local source security review found no blocking findings; it does not establish provider-backed compatibility.
+
+## Laya setup
+
+Point `PI_SESSION_MEMORY_PYTHON` at a Python 3.11 interpreter that can import Laya. The pins below identify the tested dependency and model file. Pi and npm do not require these pins; this worker does. A mismatch leaves Pi running without memory.
+
+<details>
+<summary>Pinned Laya installation and model verification</summary>
+
+Laya is 0.3.7 at commit `010bacef009c855ccba814b51f7c8e1d38ab5e3f`. The checkpoint revision is `f9ab0b228f0fc0f14d873dbc99038f135c2da1b2`. The `model.safetensors` SHA-256 is `4fa56de72383a9d3efa9cfa78955733c81b9fc8067a587ca4beb82c78107a24e`.
+
+This VCS-form install is not run by this project:
+
+```sh
+uv pip install "laya @ git+https://github.com/NandhaKishorM/laya@010bacef009c855ccba814b51f7c8e1d38ab5e3f"
+```
+
+No download command is verified here. The checkpoint is the Hugging Face cache snapshot `models--convaiinnovations--laya-typed-decisions/snapshots/f9ab0b228f0fc0f14d873dbc99038f135c2da1b2`. The hub directory is `HF_HUB_CACHE`, otherwise `$HF_HOME/hub`, otherwise `$XDG_CACHE_HOME/huggingface/hub`, otherwise `~/.cache/huggingface/hub`. `PI_SESSION_MEMORY_LAYA_CHECKPOINT` overrides that directory. Check the weights with `shasum -a 256 model.safetensors` and compare it with the SHA-256 above. To refuse a hub fetch, set `HF_HUB_OFFLINE=1` and `TRANSFORMERS_OFFLINE=1`.
+
+</details>
+
+## Check your install
+
+Start Pi and run `/memory status`. This checks that the extension loaded without starting Laya or sending a provider request. Use `/memory on` only after setup; review the confirmation before allowing generation.
+
+<details>
+<summary>Developer checks from a source checkout</summary>
+
+The first block needs no Laya cache and sends no provider request. It installs the package into a temporary Pi agent directory, checks that `/memory` is listed, checks that `pi --no-extensions` hides it, then removes it. The second block needs the two environment variables. The doc test skips that block when they are absent.
+
+<!-- verify-install:start -->
+```sh
+set -euo pipefail
+agent="$(mktemp -d)"
+trap 'rm -rf "$agent"' EXIT
+export PI_CODING_AGENT_DIR="$agent"
+export PI_OFFLINE=1
+pi --version
+node --version
+pi install "$PWD"
+loaded="$(printf '%s\n' '{"type":"get_commands","id":"commands"}' | pi --mode rpc --no-session)"
+printf '%s\n' "$loaded" | grep -F '"name":"memory"' >/dev/null
+disabled="$(printf '%s\n' '{"type":"get_commands","id":"commands"}' | pi --mode rpc --no-session --no-extensions)"
+if printf '%s\n' "$disabled" | grep -F '"name":"memory"' >/dev/null; then
+  echo "memory listed while extensions are disabled" >&2
+  exit 1
+fi
+pi remove "$PWD"
+removed="$(printf '%s\n' '{"type":"get_commands","id":"commands"}' | pi --mode rpc --no-session)"
+if printf '%s\n' "$removed" | grep -F '"name":"memory"' >/dev/null; then
+  echo "memory still listed after remove" >&2
+  exit 1
+fi
+```
+<!-- verify-install:end -->
+
+<!-- verify-laya:start -->
+```sh
+set -euo pipefail
+: "${PI_SESSION_MEMORY_PYTHON:?set PI_SESSION_MEMORY_PYTHON}"
+: "${PI_SESSION_MEMORY_LAYA_CHECKPOINT:?set PI_SESSION_MEMORY_LAYA_CHECKPOINT}"
+unset NODE_TEST_CONTEXT
+"$PI_SESSION_MEMORY_PYTHON" -m unittest discover -s worker/tests -p 'test_*.py'
+node --test test/pi/projection.test.ts
+```
+<!-- verify-laya:end -->
+
+</details>
+
+## Status
+
+Experimental. A local source security review found no blocking findings. This is not a guarantee of security. No license has been selected; publication alone does not grant permission to reuse the code. GitHub, npm, and local-path installation use the same Pi package manifest.
+
+Report problems or discuss the experiment in [GitHub issues](https://github.com/sovorn-c/pi-session-memory/issues). Include your Pi version, Python version, and `/memory status` output. Do not post session text, credentials, or private paths.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@sovorn/pi-session-memory",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension that keeps small, source-linked memories of a coding session.",
+  "homepage": "https://github.com/sovorn-c/pi-session-memory#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sovorn-c/pi-session-memory.git"
+  },
+  "bugs": { "url": "https://github.com/sovorn-c/pi-session-memory/issues" },
+  "files": ["src/", "worker/*.py"],
+  "publishConfig": { "access": "public" },
+  "keywords": ["pi-package", "pi-extension", "session-memory"],
+  "pi": { "extensions": ["./src/extension.ts"] },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*" }
+}

package/src/config.ts

@@ -0,0 +1,140 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const DEFAULT_GENERATION = false;
+export const DEFAULT_OBSERVE_AFTER_TOKENS = 10_000;
+export const DEFAULT_REFLECT_AFTER_TOKENS = 20_000;
+export const DEFAULT_PYTHON = "python3.11";
+export const MAX_CONFIG_BYTES = 16_384;
+
+export const CONFIG_KEYS = {
+  generation: { type: "boolean", default: DEFAULT_GENERATION },
+  python: { type: "string", optional: true },
+  observeAfterTokens: { type: "integer", default: DEFAULT_OBSERVE_AFTER_TOKENS },
+  reflectAfterTokens: { type: "integer", default: DEFAULT_REFLECT_AFTER_TOKENS },
+} as const;
+
+export interface MemorySettings {
+  generation: boolean;
+  python?: string;
+  observeAfterTokens: number;
+  reflectAfterTokens: number;
+}
+
+export type ConfigState = "missing" | "found" | "unusable";
+export type PythonSource = "env" | "config" | "default";
+
+export interface LoadedMemoryConfig {
+  path: string;
+  settings: MemorySettings;
+  notice: string | null;
+  state: ConfigState;
+}
+
+export interface PythonResolution {
+  command: string;
+  source: PythonSource;
+}
+
+const KNOWN_KEYS = ["generation", "python", "observeAfterTokens", "reflectAfterTokens"] as const;
+
+export function configPath(agentDir: string): string {
+  return join(agentDir, "pi-session-memory", "config.json");
+}
+
+export function loadMemoryConfig(agentDir: string): LoadedMemoryConfig {
+  const path = configPath(agentDir);
+  const missing: LoadedMemoryConfig = { path, settings: defaultSettings(), notice: null, state: "missing" };
+  let size = 0;
+  try {
+    const info = statSync(path);
+    if (info.isDirectory()) return unusable(path, "config path is a directory");
+    size = info.size;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return missing;
+    return unusable(path, "config file is unreadable");
+  }
+  if (size > MAX_CONFIG_BYTES) return unusable(path, "config is larger than 16384 bytes");
+
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return unusable(path, "config file is unreadable");
+  }
+  if (text.length === 0) return unusable(path, "config file is empty");
+  if (text.charCodeAt(0) === 0xfeff) text = text.slice(1);
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return unusable(path, "malformed JSON");
+  }
+  if (Array.isArray(parsed) || typeof parsed === "string" || !isRecord(parsed)) {
+    return unusable(path, "config root must be an object");
+  }
+  return applyObject(path, parsed);
+}
+
+export function resolvePython(env: { PI_SESSION_MEMORY_PYTHON?: string }, settings: MemorySettings): PythonResolution {
+  const fromEnv = env.PI_SESSION_MEMORY_PYTHON;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) return { command: fromEnv, source: "env" };
+  if (settings.python && settings.python.trim().length > 0) return { command: settings.python.trim(), source: "config" };
+  return { command: DEFAULT_PYTHON, source: "default" };
+}
+
+function applyObject(path: string, parsed: Record<string, unknown>): LoadedMemoryConfig {
+  const settings = defaultSettings();
+  const reasons: string[] = [];
+  const unknown = Object.keys(parsed).filter((key) => !KNOWN_KEYS.includes(key as typeof KNOWN_KEYS[number])).sort();
+  if (unknown.length > 0) reasons.push(`ignored unknown keys: ${unknown.join(", ")}`);
+
+  if ("generation" in parsed) {
+    if (typeof parsed.generation === "boolean") settings.generation = parsed.generation;
+    else {
+      settings.generation = false;
+      reasons.push("generation: expected boolean");
+    }
+  }
+  if ("python" in parsed) {
+    if (typeof parsed.python === "string" && parsed.python.trim().length > 0) settings.python = parsed.python.trim();
+    else reasons.push("python: expected non-empty string");
+  }
+  if ("observeAfterTokens" in parsed) settings.observeAfterTokens = readCadence(parsed.observeAfterTokens, "observeAfterTokens", reasons);
+  if ("reflectAfterTokens" in parsed) settings.reflectAfterTokens = readCadence(parsed.reflectAfterTokens, "reflectAfterTokens", reasons);
+
+  const hardFailure = reasons.some((reason) => !reason.startsWith("ignored unknown keys:"));
+  return {
+    path,
+    settings,
+    notice: reasons.length > 0 ? reasons.join("; ") : null,
+    state: hardFailure ? "unusable" : "found",
+  };
+}
+
+function readCadence(value: unknown, key: string, reasons: string[]): number {
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) return value;
+  reasons.push(`${key}: expected integer >= 1`);
+  return key === "reflectAfterTokens" ? DEFAULT_REFLECT_AFTER_TOKENS : DEFAULT_OBSERVE_AFTER_TOKENS;
+}
+
+function defaultSettings(): MemorySettings {
+  return {
+    generation: DEFAULT_GENERATION,
+    observeAfterTokens: DEFAULT_OBSERVE_AFTER_TOKENS,
+    reflectAfterTokens: DEFAULT_REFLECT_AFTER_TOKENS,
+  };
+}
+
+function unusable(path: string, notice: string): LoadedMemoryConfig {
+  return { path, settings: defaultSettings(), notice, state: "unusable" };
+}
+
+function errorCode(error: unknown): string | undefined {
+  return isRecord(error) && typeof error.code === "string" ? error.code : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/extension.ts

@@ -0,0 +1,10 @@
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerFormation } from "./formation.ts";
+import { registerHydration } from "./hydration.ts";
+
+export { CONFIRM_TITLE, DISCLOSURE } from "./formation.ts";
+
+export default function (pi: ExtensionAPI): void {
+  registerFormation(pi, { agentDir: () => getAgentDir() });
+  registerHydration(pi);
+}