@brianmichel/pi-noodle 0.1.0

package/src/memory/types.ts

@@ -0,0 +1,192 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+import type { JsonObject, NotificationTarget, SessionManagerLike } from "../types.ts";
+
+export type MemoryCategory =
+  | "identity"
+  | "response_style"
+  | "coding_pref"
+  | "workflow"
+  | "project";
+
+export type MemoryDurability = "durable" | "semi_durable" | "ephemeral";
+export type MemoryApplicability = "user" | "project" | "unknown";
+
+export type MemorySource = "explicit" | "heuristic" | "repetition" | "llm_extracted" | "consolidated";
+
+export type MemoryScope = {
+  userId?: string;
+  assistantId?: string;
+  sessionId?: string;
+};
+
+export type MemoryMessage = {
+  role: string;
+  content: string;
+};
+
+export type MemoryRecord = {
+  id?: string;
+  text: string;
+  category?: MemoryCategory;
+  categories: string[];
+  metadata: JsonObject;
+  score?: number;
+  scope?: MemoryScope;
+  createdAt?: number;
+  lastRetrieved?: number;
+  retrievalCount?: number;
+};
+
+export type AddMemoryInput = {
+  text?: string;
+  messages?: MemoryMessage[];
+  metadata?: JsonObject;
+  category?: MemoryCategory;
+  categories?: string[];
+  scope?: MemoryScope;
+};
+
+export type MemorySearchInput = {
+  query: string;
+  scope?: MemoryScope;
+  categories?: string[];
+  limit?: number;
+  threshold?: number;
+  filters?: JsonObject;
+};
+
+export type MemoryListInput = {
+  scope?: MemoryScope;
+};
+
+export type UpdateMemoryInput = {
+  text?: string;
+  metadata?: JsonObject;
+};
+
+export type ConversationCaptureInput = {
+  messages: MemoryMessage[];
+  metadata?: JsonObject;
+  scope?: MemoryScope;
+};
+
+export type MemoryCandidate = {
+  text: string;
+  normalized: string;
+  category: MemoryCategory;
+  durability: MemoryDurability;
+  applicability?: MemoryApplicability;
+  source: MemorySource;
+  confidence: number;
+  explicit: boolean;
+  reasons: string[];
+  metadata: JsonObject;
+};
+
+export type PrefilterResult = {
+  hasCandidate: boolean;
+  shouldRetrieve: boolean;
+  candidateReasons: string[];
+  candidates: MemoryCandidate[];
+};
+
+export type LocalSignal = {
+  key: string;
+  text: string;
+  normalized: string;
+  category: MemoryCategory;
+  durability: MemoryDurability;
+  applicability?: MemoryApplicability;
+  source: MemorySource;
+  explicit: boolean;
+  count: number;
+  lastSeenAt: number;
+  strongestConfidence: number;
+  reasons: string[];
+  metadata: JsonObject;
+  retrievalCount?: number;
+  lastRetrievedAt?: number;
+  promotedAt?: number;
+  lastPromotionScore?: number;
+  lastDecisionAction?: MemoryPolicyAction;
+};
+
+export type MemoryPolicyAction = "save" | "pending" | "discard";
+
+export type ExtractionStability = "stable" | "likely_stable" | "uncertain";
+export type ExtractionSensitivity = "safe" | "sensitive";
+
+export type ExtractionCandidate = {
+  text: string;
+  category: MemoryCategory;
+  durability: MemoryDurability;
+  confidence: number;
+  reason: string;
+  stability: ExtractionStability;
+  sensitivity: ExtractionSensitivity;
+  suggestedAction: MemoryPolicyAction;
+  applicability: MemoryApplicability;
+  applicabilityConfidence?: number;
+  applicabilityReason?: string;
+};
+
+export type MemoryPolicyDecision = {
+  action: MemoryPolicyAction;
+  score: number;
+  shouldPromote: boolean;
+  reasons: string[];
+};
+
+export type ConsolidationReport = {
+  merged: number;
+  deleted: number;
+};
+
+export type MemoryExtractorResolution = {
+  model: Model<Api>;
+  apiKey: string;
+  headers?: Record<string, string>;
+};
+
+export type MemoryCaptureEventBase = {
+  sessionManager: SessionManagerLike;
+  target?: NotificationTarget;
+  extractor?: {
+    resolve: () => Promise<MemoryExtractorResolution | null>;
+  };
+};
+
+export type MemoryCaptureEvent =
+  | (MemoryCaptureEventBase & {
+      type: "user_input";
+      text: string;
+    })
+  | (MemoryCaptureEventBase & {
+      type: "session_before_compact";
+    })
+  | (MemoryCaptureEventBase & {
+      type: "session_before_switch";
+      reason: string;
+    })
+  | (MemoryCaptureEventBase & {
+      type: "session_shutdown";
+      reason: string;
+    });
+
+export type MemoryCapturePlan = {
+  runHeuristics: boolean;
+  runLlmExtraction: boolean;
+  captureConversation: boolean;
+  consolidate: boolean;
+  extractionReason?: string;
+  conversationReason?: string;
+};
+
+export type MemoryCaptureResult = {
+  plan: MemoryCapturePlan;
+  automaticCaptureQueued: boolean;
+  llmExtractionQueued: boolean;
+  conversationCaptureQueued: boolean;
+  consolidationQueued: boolean;
+};

package/src/notifications.ts

@@ -0,0 +1,11 @@
+import type { NotificationTarget } from "./types.ts";
+
+export function notify(target: NotificationTarget | undefined, message: string, level: "info" | "error"): void {
+  if (!target) return;
+
+  try {
+    target.ui.notify(message, level);
+  } catch {
+    // ignore notify failures
+  }
+}

package/src/queue.ts

@@ -0,0 +1,42 @@
+import { notify } from "./notifications.ts";
+import type { NotificationTarget } from "./types.ts";
+import { describeError } from "./utils.ts";
+
+let nextWriteJobId = 1;
+let pendingWriteQueue: Promise<void> = Promise.resolve();
+
+export function enqueueWriteTask(options: {
+  label: string;
+  task: () => Promise<void>;
+  target?: NotificationTarget;
+  successMessage?: string;
+  onSuccess?: () => void;
+  onFailure?: () => void;
+}): number {
+  const jobId = nextWriteJobId++;
+
+  const run = async () => {
+    try {
+      await options.task();
+      if (options.successMessage) {
+        notify(options.target, options.successMessage, "info");
+      }
+      options.onSuccess?.();
+    } catch (error) {
+      options.onFailure?.();
+      const message = `${options.label} failed: ${describeError(error)}`;
+      if (options.target) {
+        notify(options.target, message, "error");
+      } else {
+        console.error(message);
+      }
+    }
+  };
+
+  pendingWriteQueue = pendingWriteQueue.catch(() => undefined).then(run);
+  return jobId;
+}
+
+export async function flushPendingWrites(): Promise<void> {
+  await pendingWriteQueue.catch(() => undefined);
+}

package/src/session.ts

@@ -0,0 +1,72 @@
+import { DEFAULT_AGENT_ID } from "./constants.ts";
+import type { MemoryMessage } from "./memory/types.ts";
+import { flushPendingWrites } from "./queue.ts";
+import type { SessionEntryLike, SessionManagerLike } from "./types.ts";
+import { extractTextContent } from "./utils.ts";
+
+export { flushPendingWrites };
+
+export function ensureMessages(text?: string, messages?: MemoryMessage[]): MemoryMessage[] {
+  if (messages && messages.length > 0) return messages;
+  if (text && text.trim()) {
+    return [{ role: "user", content: text.trim() }];
+  }
+  throw new Error("Provide either text or messages.");
+}
+
+export function resolveAssistantId(assistantId?: string): string {
+  const trimmed = assistantId?.trim();
+  return trimmed || DEFAULT_AGENT_ID;
+}
+
+export function collectSessionMessages(sessionManager: SessionManagerLike): MemoryMessage[] {
+  const branch = sessionManager.getBranch();
+  const messages: MemoryMessage[] = [];
+
+  for (const entry of branch) {
+    if (!entry || typeof entry !== "object") continue;
+    const typedEntry = entry as SessionEntryLike;
+
+    if (typedEntry.type !== "message") continue;
+    const role = typedEntry.message?.role;
+    if (role !== "user" && role !== "assistant") continue;
+
+    const content = extractTextContent(typedEntry.message?.content);
+    if (!content) continue;
+    messages.push({ role, content });
+  }
+
+  return messages;
+}
+
+export function buildSessionSignature(sessionManager: SessionManagerLike): string {
+  const sessionFile = sessionManager.getSessionFile?.() || "ephemeral";
+  const leafId = sessionManager.getLeafId?.() || "no-leaf";
+  return `${sessionFile}::${leafId}`;
+}
+
+function looksLikeToolOrCodeChatter(content: string): boolean {
+  return /```|^\$ |\bstderr\b|\bstdout\b|traceback|exception|stack trace|npm ERR!/im.test(content);
+}
+
+export function selectMemoryWorthMessages(messages: MemoryMessage[]): MemoryMessage[] {
+  const filtered = messages.filter((message) => {
+    const trimmed = message.content.trim();
+    return trimmed.length >= 20 && !looksLikeToolOrCodeChatter(trimmed);
+  });
+  return filtered.slice(-20);
+}
+
+export function selectExtractorMessages(messages: MemoryMessage[]): MemoryMessage[] {
+  const filtered = messages.filter((message) => {
+    const trimmed = message.content.trim();
+    if (trimmed.length < 24 || looksLikeToolOrCodeChatter(trimmed)) return false;
+    if (message.role === "user") return true;
+    return /\b(prefer|usually|always|never|avoid|default|remember|name is|we(?:'|’)re|we are|our stack|standardi[sz]e)\b/i.test(trimmed);
+  });
+
+  const preferred = filtered.slice(-12);
+  const userCount = preferred.filter((message) => message.role === "user").length;
+  if (preferred.length >= 4 && userCount >= 2) return preferred;
+  return messages.slice(-8).filter((message) => message.content.trim().length >= 24);
+}

package/src/tools.ts

@@ -0,0 +1,172 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+import { memoryService } from "./memory/runtime.ts";
+import type { JsonObject } from "./types.ts";
+import { formatJson } from "./utils.ts";
+
+const scopeSchema = Type.Object({
+  userId: Type.Optional(Type.String({ description: "User identifier." })),
+  assistantId: Type.Optional(Type.String({ description: "Assistant identifier." })),
+  sessionId: Type.Optional(Type.String({ description: "Session/run identifier." })),
+});
+
+const metadataSchema = Type.Object({}, { additionalProperties: true, description: "Optional metadata." });
+
+export const memoryAddTool = defineTool({
+  name: "memory_add",
+  label: "Memory Add",
+  description: "Store a memory record using the configured memory backend.",
+  promptSnippet: "Store important user or agent facts in long-term memory.",
+  promptGuidelines: [
+    "Use memory_add when the user explicitly asks to save a stable preference, identity detail, or workflow default.",
+  ],
+  parameters: Type.Object({
+    text: Type.Optional(Type.String({ description: "Convenience text memory to store." })),
+    messages: Type.Optional(
+      Type.Array(
+        Type.Object({
+          role: Type.String({ description: "Message role." }),
+          content: Type.String({ description: "Message content." }),
+        }),
+        { description: "Conversation messages to capture as memory." },
+      ),
+    ),
+    category: Type.Optional(Type.String({ description: "Primary memory category." })),
+    categories: Type.Optional(Type.Array(Type.String({ description: "Additional categories." }))),
+    scope: Type.Optional(scopeSchema),
+    metadata: Type.Optional(metadataSchema),
+  }),
+  async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+    await memoryService.add({
+      ...(params.text ? { text: params.text } : {}),
+      ...(params.messages ? { messages: params.messages } : {}),
+      ...(params.category ? { category: params.category as never } : {}),
+      ...(params.categories ? { categories: params.categories } : {}),
+      ...(params.scope ? { scope: params.scope } : {}),
+      ...(params.metadata ? { metadata: params.metadata as JsonObject } : {}),
+    });
+
+    const result = { queued: false, saved: true };
+
+    return {
+      content: [{ type: "text", text: formatJson(result) }],
+      details: result,
+    };
+  },
+});
+
+export const memorySearchTool = defineTool({
+  name: "memory_search",
+  label: "Memory Search",
+  description: "Search stored memories using the configured memory backend.",
+  promptSnippet: "Search memory for relevant saved facts.",
+  promptGuidelines: [
+    "Use memory_search before answering questions that depend on previously saved preferences or identity details.",
+  ],
+  parameters: Type.Object({
+    query: Type.String({ description: "Natural-language search query." }),
+    categories: Type.Optional(Type.Array(Type.String({ description: "Optional category filters." }))),
+    scope: Type.Optional(scopeSchema),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of results." })),
+    threshold: Type.Optional(Type.Number({ description: "Optional backend similarity threshold." })),
+    filters: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Backend-specific filters such as source, auto_saved, createdAfter, createdBefore, minRetrievalCount, maxRetrievalCount, minConfidence, metadata." })),
+  }),
+  async execute(_toolCallId, params) {
+    const result = await memoryService.search({
+      query: params.query,
+      ...(params.categories ? { categories: params.categories } : {}),
+      ...(params.scope ? { scope: params.scope } : {}),
+      ...(params.limit !== undefined ? { limit: params.limit } : {}),
+      ...(params.threshold !== undefined ? { threshold: params.threshold } : {}),
+      ...(params.filters ? { filters: params.filters as JsonObject } : {}),
+    });
+
+    return {
+      content: [{ type: "text", text: formatJson(result) }],
+      details: result,
+    };
+  },
+});
+
+export const memoryListTool = defineTool({
+  name: "memory_list",
+  label: "Memory List",
+  description: "List memories from the configured memory backend.",
+  parameters: Type.Object({
+    scope: Type.Optional(scopeSchema),
+  }),
+  async execute(_toolCallId, params) {
+    const result = await memoryService.list(params.scope);
+    return {
+      content: [{ type: "text", text: formatJson(result) }],
+      details: result,
+    };
+  },
+});
+
+export const memoryGetTool = defineTool({
+  name: "memory_get",
+  label: "Memory Get",
+  description: "Fetch a specific memory by ID.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Memory ID." }),
+  }),
+  async execute(_toolCallId, params) {
+    const result = await memoryService.get(params.id);
+    return {
+      content: [{ type: "text", text: formatJson(result) }],
+      details: result,
+    };
+  },
+});
+
+export const memoryUpdateTool = defineTool({
+  name: "memory_update",
+  label: "Memory Update",
+  description: "Update a specific memory.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Memory ID." }),
+    text: Type.Optional(Type.String({ description: "Replacement memory text." })),
+    metadata: Type.Optional(metadataSchema),
+  }),
+  async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+    await memoryService.update(params.id, {
+      ...(params.text ? { text: params.text } : {}),
+      ...(params.metadata ? { metadata: params.metadata as JsonObject } : {}),
+    });
+
+    const result = { updated: true, id: params.id };
+
+    return {
+      content: [{ type: "text", text: formatJson(result) }],
+      details: result,
+    };
+  },
+});
+
+export const memoryDeleteTool = defineTool({
+  name: "memory_delete",
+  label: "Memory Delete",
+  description: "Delete a specific memory.",
+  parameters: Type.Object({
+    id: Type.String({ description: "Memory ID." }),
+  }),
+  async execute(_toolCallId, params) {
+    await memoryService.delete(params.id);
+    const result = { deleted: true, id: params.id };
+    return {
+      content: [{ type: "text", text: formatJson(result) }],
+      details: result,
+    };
+  },
+});
+
+export const memoryTools = [
+  memoryAddTool,
+  memorySearchTool,
+  memoryListTool,
+  memoryGetTool,
+  memoryUpdateTool,
+  memoryDeleteTool,
+] as const;

package/src/types.ts

@@ -0,0 +1,81 @@
+export type NoodleDbMode = "local" | "cloud";
+
+export type NoodleEmbeddingProvider = "openai" | "lm_studio" | "ollama" | "custom";
+
+export type NoodleExtractorMode = "off" | "conservative" | "balanced" | "proactive";
+
+export type NoodleExtractorConfig = {
+  /**
+   * Behavior profile for proactive extraction.
+   * off = disable extractor
+   * conservative = fewer runs, higher save threshold
+   * balanced = default tradeoff
+   * proactive = more candidate discovery, more review load
+   */
+  mode?: NoodleExtractorMode;
+  /**
+   * Model ID to use for extraction (e.g. "claude-haiku-4-5-20251001").
+   * Must be a model already configured in Pi. Defaults to Pi's configured
+   * extractor default when unset.
+   */
+  model?: string;
+  /** Number of user turns between automatic extraction runs. Defaults by mode when unset. */
+  triggerEvery?: number;
+  /** Show the extractor debug widget in Pi while developing. */
+  debug?: boolean;
+};
+
+export type NoodleConfig = {
+  db: {
+    mode: NoodleDbMode;
+    /** File path for local mode */
+    path: string;
+    /** Turso URL for cloud mode (e.g. libsql://my-db.turso.io) */
+    url?: string;
+    /** Turso auth token for cloud mode */
+    authToken?: string;
+  };
+  embedding: {
+    /** Human-readable provider label (openai, lm_studio, ollama, custom) */
+    provider: NoodleEmbeddingProvider;
+    /** API key or placeholder */
+    apiKey: string;
+    /** Base URL for the /v1/embeddings endpoint */
+    baseUrl: string;
+    /** Model name */
+    model: string;
+    /** Optional explicit embedding dimension override for custom/nonstandard providers. */
+    dimensions?: number;
+  };
+  extractor?: NoodleExtractorConfig;
+};
+
+export type NoodleConfigPartial = {
+  db?: Partial<NoodleConfig["db"]> & { mode?: NoodleDbMode };
+  embedding?: Partial<NoodleConfig["embedding"]>;
+  extractor?: Partial<NoodleExtractorConfig>;
+};
+
+export type JsonObject = Record<string, unknown>;
+
+export type NotifyLevel = "info" | "error";
+
+export type NotificationTarget = {
+  ui: {
+    notify: (message: string, level: NotifyLevel) => void;
+  };
+};
+
+export type SessionManagerLike = {
+  getBranch: () => unknown[];
+  getSessionFile?: () => string | null | undefined;
+  getLeafId?: () => string | null | undefined;
+};
+
+export type SessionEntryLike = {
+  type?: string;
+  message?: {
+    role?: string;
+    content?: unknown;
+  };
+};

package/src/utils.ts

@@ -0,0 +1,68 @@
+import type { JsonObject } from "./types.ts";
+
+export function maskSecret(value: string): string {
+  if (value.length <= 8) return "*".repeat(value.length);
+  return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function formatJson(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+export function isJsonObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function asStringArray(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+export function asFiniteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function parseJsonObject(value: unknown, fallback: JsonObject = {}): JsonObject {
+  if (typeof value !== "string") return fallback;
+  try {
+    const parsed = JSON.parse(value);
+    return isJsonObject(parsed) ? parsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function parseJsonStringArray(value: unknown, fallback: string[] = []): string[] {
+  if (typeof value !== "string") return fallback;
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed === "string" || Array.isArray(parsed)) {
+      return asStringArray(parsed);
+    }
+    return fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function extractTextContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+
+  return content
+    .flatMap((part) => {
+      if (!part || typeof part !== "object") return [];
+      const typedPart = part as { type?: string; text?: string };
+      if (typedPart.type === "text" && typeof typedPart.text === "string") {
+        return [typedPart.text];
+      }
+      return [];
+    })
+    .join("\n")
+    .trim();
+}

package/src/web/dev.ts

@@ -0,0 +1,7 @@
+import { memoryService } from "../memory/runtime.ts";
+import { startMemoryExplorer } from "./server.ts";
+
+const port = parseInt(process.env["PORT"] ?? "3000", 10);
+
+startMemoryExplorer(memoryService, port, { dev: true, openBrowser: true });
+console.log("Editing src/web/index.html will hot-reload the browser. Ctrl+C to stop.");