@brianmichel/pi-noodle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Michel
+
+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,231 @@
+# pi-noodle
+
+Long-term memory for Pi.
+
+This repo is building a small, opinionated memory system that tries to be:
+
+- **useful** — retrieve facts that actually help future turns
+- **safe** — avoid saving temporary or sensitive content
+- **automatic** — capture durable signals from normal conversation
+- **inspectable** — review what was saved, pending, or discarded
+
+Under the hood it uses [libSQL](https://turso.tech/libsql) for storage and vector similarity search for retrieval.
+
+![](img/dashboard.jpeg)
+
+## Quick start
+
+```bash
+# Install as a Pi extension
+pi install @brianmichel/pi-noodle
+
+# In Pi, configure interactively
+/noodle settings
+```
+
+The setup screen shows the full config on one page:
+1. Database mode — local file or Turso Cloud
+2. Embedding provider — OpenAI, LM Studio, Ollama, or custom
+3. Relevant fields update in place as you switch modes/providers
+4. Required fields are validated before save
+
+Settings are saved to `~/.pi/noodle/config.json` — memories travel with you across all projects.
+
+## `/noodle` command
+
+```
+/noodle                  Show current config (paths, endpoint, masked API key)
+/noodle remember <text>  Save a memory directly
+/noodle forget <query>   Find and delete a memory
+/noodle edit <query>     Find and update a memory
+/noodle review           Review recent auto-saved memories
+/noodle settings         Interactive single-screen configuration editor with validation
+/noodle setup            Alias for /noodle settings
+/noodle init             Create a default config file for manual editing
+/noodle web              Start the Memory Explorer (auto-stops when all tabs close)
+/noodle web stop         Stop the explorer immediately
+/noodle web dev          Dev mode — hot reload on save, use web stop when done
+/noodle web 8080         Start on a custom port
+```
+
+For UI development outside Pi, run `npm run web:dev` from the repo — it connects to your configured database and reloads the browser whenever you edit `src/web/index.html`.
+
+### Memory Explorer Web UI
+
+Launch a dark-themed web interface to browse, search, and visualize your memories:
+
+- **Live stats** — total memories, categories, scopes
+- **Category filter** — dropdown of all stored categories
+- **Text search** — substring matching on memory text
+- **Dark mode** — GitHub-inspired color scheme
+
+Run `/noodle web` in Pi to open the explorer in your browser. The server runs in a background process and **shuts down automatically ~2 seconds after you close all tabs**. Use `/noodle web stop` to kill it manually.
+
+## Config file
+
+`~/.pi/noodle/config.json`:
+
+```json
+{
+  "db": {
+    "mode": "local",
+    "path": "/Users/you/.pi/noodle/memories.db"
+  },
+  "embedding": {
+    "provider": "openai",
+    "apiKey": "sk-...",
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "text-embedding-3-small"
+  }
+}
+```
+
+### Cloud mode (Turso)
+
+```json
+{
+  "db": {
+    "mode": "cloud",
+    "url": "libsql://my-db-org.turso.io",
+    "authToken": "eyJ..."
+  },
+  "embedding": {
+    "provider": "openai",
+    "apiKey": "sk-...",
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "text-embedding-3-small"
+  },
+  "extractor": {
+    "mode": "balanced",
+    "model": "deepseek/deepseek-v4-flash:free",
+    "triggerEvery": 10
+  }
+}
+```
+
+### Memory modes
+
+When memory mode is not `off`, capture uses a **unified capture pipeline** with policy-gated persistence:
+
+- `conservative`
+  - fewer extraction runs
+  - higher bar for auto-save
+  - softer inferences are usually discarded until reinforced
+- `balanced` (recommended default)
+  - durable facts can auto-save
+  - medium-confidence preferences go to `/noodle review`
+- `proactive`
+  - more frequent extraction
+  - more candidate discovery
+  - pending review queue grows faster, but saved-memory safety rules stay the same
+
+The extractor model is configurable too, so you can tune quality/speed/cost separately from behavior mode.
+
+## Environment variable overrides
+
+Env vars take priority over the config file:
+
+| Variable | Overrides |
+|---|---|
+| `NOODLE_CONFIG_PATH` | Config file location |
+| `NOODLE_DB_PATH` | Local DB path |
+| `NOODLE_DB_URL` | Cloud DB URL |
+| `NOODLE_DB_TOKEN` | Cloud DB auth token |
+| `OPENAI_API_KEY` | Embedding API key |
+| `EMBEDDING_BASE_URL` | Embedding endpoint URL |
+| `EMBEDDING_MODEL` | Embedding model name |
+| `NOODLE_EXTRACTOR_MODE` | Memory mode: off / conservative / balanced / proactive |
+| `NOODLE_EXTRACTOR_MODEL` | Extractor model ID |
+| `NOODLE_EXTRACTOR_TRIGGER_EVERY` | Automatic extraction cadence in user turns |
+| `NOODLE_EXTRACTOR_DEBUG` | Show the extractor debug widget: true / false |
+
+## Architecture
+
+```text
+Pi lifecycle events
+  └─► MemoryService.capture(event)
+        ├─► heuristic capture
+        ├─► optional LLM extraction
+        ├─► candidate promotion policy
+        └─► conversation capture / consolidation when needed
+                    │
+                    ▼
+              MemoryBackend
+                    │
+               TursoBackend
+               ├─► libSQL (local or cloud)
+               └─► Embedder
+```
+
+### Capture pipeline
+
+```text
+input / compact / switch / shutdown
+  │
+  └─► MemoryService.capture(event)
+        │
+        ├─► heuristic prefilter
+        │      ├─ blocks sensitive / temporary content
+        │      └─ catches explicit memory asks
+        │
+        ├─► optional LLM extraction
+        │      └─ turns conversation context into memory candidates
+        │
+        ├─► local promotion policy
+        │      ├─ save     → durable memory DB
+        │      ├─ pending  → /noodle review only
+        │      └─ discard  → dropped
+        │
+        └─► retrieval injects only saved memories
+```
+
+### Why it is shaped this way
+
+- Pi only tells the memory system **what event happened**
+- `MemoryService` decides **which capture stages should run**
+- heuristic and LLM candidates share the **same promotion path**
+- pending memories stay out of retrieval until reviewed or reinforced
+
+### What gets stored
+
+Every memory is a row in SQLite with `text`, `embedding` (F32_BLOB), `category`, `categories`, `scope` (userId/assistantId/sessionId), and arbitrary `metadata`.
+
+### Search
+
+Vector similarity via `vector_distance_cos()` in libSQL, ranked by cosine distance, post-filtered by category and threshold.
+
+### Policy and review
+
+The system intentionally separates:
+
+- **detection** — heuristics and LLM extraction find memory candidates
+- **promotion** — local policy decides save / pending / discard
+- **retrieval** — only saved memories are injected into prompts
+
+That keeps the system proactive without letting low-confidence guesses pollute retrieval. Pending candidates stay visible in `/noodle review` but are **not** injected until promoted.
+
+## File layout
+
+```
+src/
+├── config.ts              # Config resolution (~/.pi/noodle/config.json + env vars)
+├── config-screen.ts       # Flat single-screen config editor for /noodle settings
+├── constants.ts           # DEFAULT_AGENT_ID
+├── types.ts               # NoodleConfig, JsonObject, NotificationTarget, etc.
+├── utils.ts               # maskSecret, describeError, formatJson, extractTextContent
+├── commands.ts            # /noodle command + interactive setup entrypoint
+├── extension.ts           # Pi extension lifecycle hooks
+├── tools.ts               # memory_add / search / list / get / update / delete
+├── session.ts             # Session message collection
+├── queue.ts               # Sequential async write queue
+├── notifications.ts       # UI notification helpers
+└── memory/
+    ├── backend.ts         # MemoryBackend interface
+    ├── types.ts           # MemoryRecord, MemoryScope, etc.
+    ├── turso-backend.ts   # TursoBackend (libSQL + vector search)
+    ├── embedder.ts        # Embedder type
+    ├── embedders/         # openai.ts, lm-studio.ts
+    ├── service.ts         # MemoryService (event-driven capture pipeline + promotion)
+    ├── policy.ts          # Heuristics (classification, repetition, retrieval)
+    └── runtime.ts         # Wiring (config + TursoBackend + MemoryService)
+```

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@brianmichel/pi-noodle",
+  "version": "0.1.0",
+  "description": "Long-term memory for Pi — local libSQL database with vector search.",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "pi.dev",
+    "pi-package",
+    "pi-extension",
+    "pi-plugin",
+    "ai-agent",
+    "agent-memory",
+    "memory",
+    "libsql",
+    "turso",
+    "vector-search"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brianmichel/pi-noodle.git"
+  },
+  "homepage": "https://github.com/brianmichel/pi-noodle#readme",
+  "bugs": {
+    "url": "https://github.com/brianmichel/pi-noodle/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "npm run check",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "clean": "echo 'nothing to clean'",
+    "test": "node --test --experimental-strip-types test/**/*.test.ts",
+    "web:dev": "bun run src/web/dev.ts"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@libsql/client": "^0.15.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "^0.75.5",
+    "@types/bun": "^1.2.0",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md
+
+This file applies to this entire repository.
+
+## Goal
+
+We are trying to build a minimal, high-quality memory system for the Pi.dev agent harness. We aim to have a high quality test suite to help prove the efficacy of this project. It should be straight forward for memories to be stored, and retrieved. Ideally this happens automatically for the user.
+
+## Type safety
+
+Prefer creating types where needed to represent things instead of just strings. We like types since they help us better understand and reason about our code. Use the TypeScript type system to make contracts clear, and ensure that side effects are easily dealt with.
+
+## Tooling
+
+This project uses mise to provide a unified interface into dependencies and tasks. The following tasks are available:
+
+- `mise check`: run the TypeScript type checker
+- `mise install`: install any dependencies
+- `mise precommit`: run precommit validation
+- `mise test`: runs this project's unit test suite.
+
+## Dead Code & Comments
+
+- Delete dead code. Do not deprecate it, alias it, or leave it behind "for consumers." This is a private monorepo, not a published library.
+- When a refactor replaces an interface or flow, remove the superseded entrypoints in the same change. Do not keep compatibility wrappers, transitional fallbacks, or duplicate code paths unless the user explicitly asks for a staged migration.
+- Update tests and callers to the new seam instead of preserving the old one.
+- Do not add decorative section-divider comments (e.g. `// -----------`).
+- Do not add comments that restate what the code already says.
+- JSDoc on public package exports is expected.
+
+## Validation
+
+You can validate your work by running the precommit task and ensure it has a normal exit status and there is no abnormal output.

package/src/commands/index.ts

@@ -0,0 +1,51 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { resolveConfigPath, writeConfig } from "../config.ts";
+import { runEdit, runForget, runRemember } from "./memory-crud.ts";
+import { runReview } from "./review.ts";
+import { runSetup } from "./setup.ts";
+import { runStatus } from "./status.ts";
+import type { CtxUi } from "./ui.ts";
+import { runWeb } from "./web.ts";
+
+export function registerCommands(pi: ExtensionAPI): void {
+  pi.registerCommand("noodle", {
+    description: "Noodle memory — status, remember/forget/edit, review, and web explorer",
+    handler: async (args, ctx) => {
+      const sub = args.trim();
+      const ui = ctx.ui as unknown as CtxUi;
+
+      if (sub === "settings" || sub === "setup") {
+        await runSetup(ui);
+        return;
+      }
+      if (sub === "review") {
+        await runReview(ui);
+        return;
+      }
+      if (sub.startsWith("remember")) {
+        await runRemember(ui, sub.slice("remember".length).trim());
+        return;
+      }
+      if (sub.startsWith("forget")) {
+        await runForget(ui, sub.slice("forget".length).trim());
+        return;
+      }
+      if (sub.startsWith("edit")) {
+        await runEdit(ui, sub.slice("edit".length).trim());
+        return;
+      }
+      if (sub === "init") {
+        writeConfig({});
+        ctx.ui.notify(`Created config at ${resolveConfigPath()}. Run /noodle settings to configure.`, "info");
+        return;
+      }
+      if (sub.startsWith("web")) {
+        await runWeb(ui, sub);
+        return;
+      }
+
+      runStatus(ui);
+    },
+  });
+}

package/src/commands/memory-crud.ts

@@ -0,0 +1,136 @@
+import { memoryService } from "../memory/runtime.ts";
+import type { MemoryRecord } from "../memory/types.ts";
+import { describeError } from "../utils.ts";
+import type { CtxUi } from "./ui.ts";
+
+export async function runRemember(ui: CtxUi, initialText: string): Promise<void> {
+  try {
+    const text = (initialText || await ui.input("Memory to save", "") || "").trim();
+    if (!text) {
+      ui.notify("Nothing saved — memory text is required.", "info");
+      return;
+    }
+
+    await memoryService.add({
+      text,
+      metadata: {
+        source: "manual_command",
+        auto_saved: false,
+      },
+    });
+    ui.notify(`Saved memory: ${summarizeMemory(text)}`, "info");
+  } catch (error) {
+    ui.notify(`Remember failed: ${describeError(error)}`, "error");
+  }
+}
+
+export async function runForget(ui: CtxUi, queryText: string): Promise<void> {
+  try {
+    const query = (queryText || await ui.input("Find memory to forget", "") || "").trim();
+    if (!query) {
+      ui.notify("Forget cancelled — enter a memory query.", "info");
+      return;
+    }
+
+    const target = await pickMemoryForAction(ui, query, "delete");
+    if (!target?.id) return;
+
+    const ok = await ui.confirm("Delete this memory?", target.text);
+    if (!ok) {
+      ui.notify("Forget cancelled.", "info");
+      return;
+    }
+
+    await memoryService.delete(target.id);
+    ui.notify(`Deleted memory: ${summarizeMemory(target.text)}`, "info");
+  } catch (error) {
+    ui.notify(`Forget failed: ${describeError(error)}`, "error");
+  }
+}
+
+export async function runEdit(ui: CtxUi, queryText: string): Promise<void> {
+  try {
+    const query = (queryText || await ui.input("Find memory to edit", "") || "").trim();
+    if (!query) {
+      ui.notify("Edit cancelled — enter a memory query.", "info");
+      return;
+    }
+
+    const target = await pickMemoryForAction(ui, query, "edit");
+    if (!target?.id) return;
+
+    const replacement = (await ui.input("Replacement text", target.text) || "").trim();
+    if (!replacement) {
+      ui.notify("Edit cancelled — replacement text is required.", "info");
+      return;
+    }
+    if (replacement === target.text) {
+      ui.notify("No changes made.", "info");
+      return;
+    }
+
+    await memoryService.update(target.id, {
+      text: replacement,
+      metadata: {
+        ...target.metadata,
+        source: "manual_edit",
+        updated_from: target.text,
+      },
+    });
+    ui.notify(`Updated memory: ${summarizeMemory(replacement)}`, "info");
+  } catch (error) {
+    ui.notify(`Edit failed: ${describeError(error)}`, "error");
+  }
+}
+
+async function pickMemoryForAction(
+  ui: CtxUi,
+  query: string,
+  action: "edit" | "delete",
+): Promise<MemoryRecord | null> {
+  const matches = await findMemoryMatches(query);
+  if (matches.length === 0) {
+    ui.notify(`No memories matched: ${query}`, "info");
+    return null;
+  }
+  if (matches.length === 1) {
+    return matches[0] ?? null;
+  }
+
+  ui.notify(`Top matches for ${action}:`, "info");
+  for (let index = 0; index < matches.length; index += 1) {
+    ui.notify(`[${index + 1}] ${summarizeMemory(matches[index]!.text)}`, "info");
+  }
+
+  const raw = (await ui.input(`Choose memory to ${action} (1-${matches.length})`, "1") || "").trim();
+  const index = parseInt(raw, 10) - 1;
+  if (Number.isNaN(index) || index < 0 || index >= matches.length) {
+    ui.notify(`Invalid selection — cancelled ${action}.`, "info");
+    return null;
+  }
+
+  return matches[index] ?? null;
+}
+
+async function findMemoryMatches(query: string): Promise<MemoryRecord[]> {
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) return [];
+
+  const semantic = await memoryService.search({ query, limit: 8 }).catch(() => []);
+  const listed = await memoryService.list();
+  const substring = listed.filter((memory) => memory.text.toLowerCase().includes(normalized));
+
+  const deduped = new Map<string, MemoryRecord>();
+  for (const memory of [...semantic, ...substring]) {
+    const key = memory.id ?? memory.text;
+    if (!deduped.has(key)) deduped.set(key, memory);
+  }
+
+  return Array.from(deduped.values()).slice(0, 8);
+}
+
+function summarizeMemory(text: string, max = 80): string {
+  const singleLine = text.replace(/\s+/g, " ").trim();
+  if (singleLine.length <= max) return singleLine;
+  return `${singleLine.slice(0, Math.max(0, max - 1))}…`;
+}