agent-working-memory 0.8.5 → 0.8.7

package/src/engine/staging.ts

@@ -1,74 +1,74 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Staging Buffer — weak signal handler.
- *
- * Observations that don't meet the salience threshold for active memory
- * go to staging. The staging buffer periodically:
- *   1. Checks staged engrams against active memory for resonance
- *   2. Promotes resonant engrams to active
- *   3. Discards expired engrams that never resonated
- *
- * Modeled on hippocampal consolidation — provisional encoding
- * that only persists if reactivated.
- */
-
-import type { IEngramStore as EngramStore } from '../storage/store.js';
-import type { ActivationEngine } from './activation.js';
-
-export class StagingBuffer {
-  private store: EngramStore;
-  private engine: ActivationEngine;
-  private checkInterval: ReturnType<typeof setInterval> | null = null;
-
-  constructor(store: EngramStore, engine: ActivationEngine) {
-    this.store = store;
-    this.engine = engine;
-  }
-
-  /**
-   * Start the periodic staging check.
-   */
-  start(intervalMs: number = 60_000): void {
-    this.checkInterval = setInterval(() => this.sweep(), intervalMs);
-  }
-
-  stop(): void {
-    if (this.checkInterval) {
-      clearInterval(this.checkInterval);
-      this.checkInterval = null;
-    }
-  }
-
-  /**
-   * Sweep staged engrams: promote or discard.
-   */
-  async sweep(): Promise<{ promoted: string[]; discarded: string[] }> {
-    const promoted: string[] = [];
-    const discarded: string[] = [];
-
-    const expired = await this.store.getExpiredStaging();
-    for (const engram of expired) {
-      // Check if this engram resonates with active memory
-      const results = await this.engine.activate({
-        agentId: engram.agentId,
-        context: `${engram.concept} ${engram.content}`,
-        limit: 3,
-        minScore: 0.3,
-        internal: true,
-      });
-
-      if (results.length > 0) {
-        // Resonance found — promote to active
-        await this.store.updateStage(engram.id, 'active');
-        promoted.push(engram.id);
-      } else {
-        // No resonance — discard
-        await this.store.deleteEngram(engram.id);
-        discarded.push(engram.id);
-      }
-    }
-
-    return { promoted, discarded };
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Staging Buffer — weak signal handler.
+ *
+ * Observations that don't meet the salience threshold for active memory
+ * go to staging. The staging buffer periodically:
+ *   1. Checks staged engrams against active memory for resonance
+ *   2. Promotes resonant engrams to active
+ *   3. Discards expired engrams that never resonated
+ *
+ * Modeled on hippocampal consolidation — provisional encoding
+ * that only persists if reactivated.
+ */
+
+import type { IEngramStore as EngramStore } from '../storage/store.js';
+import type { ActivationEngine } from './activation.js';
+
+export class StagingBuffer {
+  private store: EngramStore;
+  private engine: ActivationEngine;
+  private checkInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(store: EngramStore, engine: ActivationEngine) {
+    this.store = store;
+    this.engine = engine;
+  }
+
+  /**
+   * Start the periodic staging check.
+   */
+  start(intervalMs: number = 60_000): void {
+    this.checkInterval = setInterval(() => this.sweep(), intervalMs);
+  }
+
+  stop(): void {
+    if (this.checkInterval) {
+      clearInterval(this.checkInterval);
+      this.checkInterval = null;
+    }
+  }
+
+  /**
+   * Sweep staged engrams: promote or discard.
+   */
+  async sweep(): Promise<{ promoted: string[]; discarded: string[] }> {
+    const promoted: string[] = [];
+    const discarded: string[] = [];
+
+    const expired = await this.store.getExpiredStaging();
+    for (const engram of expired) {
+      // Check if this engram resonates with active memory
+      const results = await this.engine.activate({
+        agentId: engram.agentId,
+        context: `${engram.concept} ${engram.content}`,
+        limit: 3,
+        minScore: 0.3,
+        internal: true,
+      });
+
+      if (results.length > 0) {
+        // Resonance found — promote to active
+        await this.store.updateStage(engram.id, 'active');
+        promoted.push(engram.id);
+      } else {
+        // No resonance — discard
+        await this.store.deleteEngram(engram.id);
+        discarded.push(engram.id);
+      }
+    }
+
+    return { promoted, discarded };
+  }
+}

package/src/mcp.ts

@@ -6,7 +6,7 @@
  * Runs as a stdio-based MCP server that Claude Code connects to directly.
  * Uses the storage and engine layers in-process (no HTTP overhead).
  *
- * Tools exposed (12):
+ * Tools exposed (16):
  *   memory_write       — store a memory (salience filter decides disposition)
  *   memory_recall      — activate memories by context (cognitive retrieval)
  *   memory_feedback    — report whether a recalled memory was useful
@@ -19,6 +19,10 @@
  *   memory_task_update — change task status, priority, or blocking
  *   memory_task_list   — list tasks filtered by status
  *   memory_task_next   — get the highest-priority actionable task
+ *   memory_task_begin  — start a task (auto-checkpoint + recall)
+ *   memory_task_end    — end a task (write summary + checkpoint)
+ *   compress_output    — encode structured tool output as TOON (token-efficient, lossless)
+ *   retrieve_original  — get the verbatim source for a compress_output ref
  *
  * Run: npx tsx src/mcp.ts
  * Config: add to ~/.claude.json or .mcp.json
@@ -71,6 +75,7 @@ import { DEFAULT_AGENT_CONFIG } from './types/agent.js';
 import { embed } from './core/embeddings.js';
 import { startSidecar } from './hooks/sidecar.js';
 import { initLogger, log, getLogPath } from './core/logger.js';
+import { liteCompress, retrieveOriginal } from './core/lite-compress.js';
 import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-decisions.js';
 
 // --- Incognito Mode ---
@@ -81,7 +86,7 @@ const INCOGNITO = process.env.AWM_INCOGNITO === '1' || process.env.AWM_INCOGNITO
 
 if (INCOGNITO) {
   console.error('AWM: incognito mode — all memory tools disabled, nothing will be recorded');
-  const server = new McpServer({ name: 'agent-working-memory', version: '0.8.5' });
+  const server = new McpServer({ name: 'agent-working-memory', version: '0.8.7' });
   const transport = new StdioServerTransport();
   server.connect(transport).catch(err => {
     console.error('MCP server failed:', err);
@@ -94,7 +99,20 @@ if (INCOGNITO) {
 
 const BACKEND: StoreBackend = getConfiguredBackend();
 const DB_PATH = process.env.AWM_DB_PATH ?? (BACKEND === 'pglite' ? 'memory-pglite' : 'memory.db');
-const AGENT_ID = process.env.AWM_AGENT_ID ?? process.env.WORKER_NAME ?? 'claude-code';
+
+// Fallback agent selection when AWM_AGENT_ID/WORKER_NAME are unset: derive from
+// the project directory so plain `claude` launches still bind to the right
+// store. Personal-Projects -> 'personal'; everything else -> 'work' (the
+// primary store). MUST stay in sync with the SessionStart hook
+// (~/.claude/hooks/awm-session-start.ps1) so the hook's restore and the
+// server's reads/writes never diverge. Guard the AWM package's own path
+// (it lives under Personal-Projects) so a stray server cwd can't mis-bind.
+function deriveAgentFromDir(): string {
+  const dir = (process.env.CLAUDE_PROJECT_DIR ?? process.cwd()).replace(/\\/g, '/');
+  if (/\/AgentSynapse\//i.test(dir)) return 'work';
+  return /\/Personal-Projects(\/|$)/i.test(dir) ? 'personal' : 'work';
+}
+const AGENT_ID = process.env.AWM_AGENT_ID ?? process.env.WORKER_NAME ?? deriveAgentFromDir();
 const HOOK_PORT = parseInt(process.env.AWM_HOOK_PORT ?? '8401', 10);
 const HOOK_SECRET = process.env.AWM_HOOK_SECRET ?? null;
 
@@ -123,7 +141,7 @@ let coordDb: import('better-sqlite3').Database | null = null;
 
 const server = new McpServer({
   name: 'agent-working-memory',
-  version: '0.8.5',
+  version: '0.8.7',
 });
 
 server.registerResource(
@@ -1080,6 +1098,54 @@ This captures what was accomplished so future sessions can recall it.`,
   }
 );
 
+server.tool(
+  'compress_output',
+  `Compress a STRUCTURED tool output (JSON object/array, query rows, log records) into TOON —
+a compact, schema-aware tabular encoding — before putting it in your context. Cuts ~50-65%
+of the tokens on uniform arrays at zero comprehension cost (validated: models read TOON as
+accurately as JSON). Use this on large tool results you need to keep in context.
+
+Output-only and safe: it never changes the data. Non-JSON / prose is returned unchanged.
+TOON is only emitted when it reproduces the input exactly (self-verified round-trip);
+otherwise you get plain JSON back. When compressed, you also get a 'ref' — call
+retrieve_original(ref) to get the verbatim source back if you ever need it.`,
+  {
+    output: z.string().describe('The tool output to compress — JSON text (preferred) or any string. Non-JSON is returned unchanged.'),
+    min_saving_chars: z.number().optional().describe('Only emit TOON if it saves at least this many characters (default 40).'),
+  },
+  async (params) => {
+    const r = liteCompress(params.output, { minSavingChars: params.min_saving_chars });
+    log(AGENT_ID, 'compress', `${r.format} ${r.charsBefore}->${r.charsAfter} chars (${(r.ratio * 100).toFixed(0)}%)${r.ref ? ` ref=${r.ref}` : ''}`);
+    const header = r.format === 'toon'
+      ? `[TOON, ${(r.ratio * 100).toFixed(0)}% smaller — compact lossless JSON; read as data, ref=${r.ref}]\n`
+      : '';
+    return {
+      content: [{ type: 'text' as const, text: header + r.text }],
+    };
+  }
+);
+
+server.tool(
+  'retrieve_original',
+  `Retrieve the verbatim original text for a 'ref' returned by compress_output. Use this when
+you need the exact, uncompressed source (e.g. to pass it to another tool unchanged). Returns
+an error if the ref has expired (originals are kept for the most recent compressions only).`,
+  {
+    ref: z.string().describe('The ref handle returned by compress_output (e.g. "awm_orig_12").'),
+  },
+  async (params) => {
+    const original = retrieveOriginal(params.ref);
+    if (original === undefined) {
+      return {
+        content: [{ type: 'text' as const, text: `Error: ref "${params.ref}" not found or expired.` }],
+      };
+    }
+    return {
+      content: [{ type: 'text' as const, text: original }],
+    };
+  }
+);
+
 // --- Start ---
 
 async function main() {

package/src/storage/factory.ts

@@ -1,147 +1,147 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Storage backend factory.
- *
- * Picks between SQLite (mature, full features) and PGlite (portable, async,
- * pgvector). Both backends satisfy the IEngramStore contract — the cognitive
- * engines work with either through `await`.
- *
- *   AWM_STORE_BACKEND=sqlite  — better-sqlite3 + FTS5 + BLOB embeddings
- *   AWM_STORE_BACKEND=pglite  — PGlite + pgvector + tsvector
- *
- * **Backend selection (v0.8.5):** auto-detect on disk when the env var is
- * unset, so upgrading users on existing `memory.db` files keep working
- * without setting anything. Order of precedence:
- *
- *   1. `AWM_STORE_BACKEND` env var (explicit override — always wins).
- *   2. Auto-detect: if `memory-pglite/` exists on disk → pglite.
- *   3. Auto-detect: else if `memory.db` exists on disk → sqlite.
- *   4. Fall back to sqlite (the default for fresh installs).
- *
- * If `AWM_STORE_BACKEND` is set but the on-disk state disagrees (e.g. env
- * says pglite but only `memory.db` is present), `openStore` prints a one-line
- * warning suggesting `awm migrate`. The env var still wins — we never
- * silently switch backends behind the user's back.
- *
- * The `AWM_DB_PATH` env var carries the file path (SQLite) or directory
- * path (PGlite). When unset, default is `memory.db` (sqlite) or
- * `memory-pglite/` (pglite).
- *
- * **Feature parity gaps** (see `docs/pglite-feature-parity.md`):
- * a few legacy code paths reach for SQLite-specific methods
- * (coordination plugin needs `store.getDb()`, slim-cache warming, hot
- * backups). PGlite-backed AWM is fully functional for the cognitive
- * engines (write, recall, consolidation, retraction, eviction). Opt-in
- * `AWM_STORE_BACKEND=pglite` skips the SQLite-only extras.
- */
-
-import { existsSync, statSync } from 'node:fs';
-import type { IEngramStore } from './store.js';
-
-export type StoreBackend = 'sqlite' | 'pglite';
-
-/**
- * Auto-detect the backend from on-disk state. Used when `AWM_STORE_BACKEND`
- * is unset. Looks in the current working directory; honors `AWM_DB_PATH`
- * if it points at a known shape.
- */
-function detectBackendFromDisk(): StoreBackend | null {
-  // If AWM_DB_PATH is set, infer from its shape.
-  const explicitPath = process.env.AWM_DB_PATH;
-  if (explicitPath && existsSync(explicitPath)) {
-    try {
-      const stat = statSync(explicitPath);
-      if (stat.isDirectory()) return 'pglite'; // PGlite uses a directory
-      if (stat.isFile()) return 'sqlite';      // SQLite is a single file
-    } catch { /* fall through */ }
-  }
-
-  // Otherwise look for the conventional defaults in cwd.
-  // PGlite directory wins over SQLite file when both exist — assume the
-  // user actively migrated and forgot to set the env var. We warn below.
-  if (existsSync('memory-pglite')) return 'pglite';
-  if (existsSync('memory.db')) return 'sqlite';
-  return null;
-}
-
-export function getConfiguredBackend(): StoreBackend {
-  const raw = process.env.AWM_STORE_BACKEND;
-  if (raw !== undefined && raw !== '') {
-    const normalized = raw.toLowerCase();
-    if (normalized === 'pglite') return 'pglite';
-    if (normalized === 'sqlite') return 'sqlite';
-    console.warn(`Unknown AWM_STORE_BACKEND=${raw}; falling back to sqlite`);
-    return 'sqlite';
-  }
-  // Env unset → auto-detect from on-disk state.
-  const detected = detectBackendFromDisk();
-  return detected ?? 'sqlite';
-}
-
-export function getConfiguredPath(): string {
-  if (process.env.AWM_DB_PATH) return process.env.AWM_DB_PATH;
-  return getConfiguredBackend() === 'pglite' ? 'memory-pglite' : 'memory.db';
-}
-
-/**
- * Print a one-line warning to stderr when the configured backend disagrees
- * with what's actually on disk. We never fail or silently switch backends
- * — the explicit configuration always wins. The warning helps users notice
- * that they may have stranded data on the other backend.
- */
-function warnIfBackendDisagreesWithDisk(backend: StoreBackend, path: string): void {
-  if (process.env.AWM_SUPPRESS_BACKEND_WARNINGS === '1') return;
-
-  // Only warn when env var was explicit (auto-detect already follows disk).
-  if (!process.env.AWM_STORE_BACKEND) return;
-
-  const otherPath = backend === 'pglite' ? 'memory.db' : 'memory-pglite';
-  const otherBackend = backend === 'pglite' ? 'sqlite' : 'pglite';
-
-  // The "real" check: configured target doesn't exist yet (fresh / empty) AND
-  // the other backend's conventional file exists with data. Likely stranded.
-  const configuredExists = existsSync(path);
-  const otherExists = existsSync(otherPath);
-
-  if (!configuredExists && otherExists) {
-    console.warn(
-      `[awm] AWM_STORE_BACKEND=${backend} but no data at "${path}". ` +
-      `Existing ${otherBackend} data at "${otherPath}" — run \`awm migrate\` ` +
-      `to convert it to ${backend}, or unset AWM_STORE_BACKEND to use ${otherBackend}. ` +
-      `Suppress with AWM_SUPPRESS_BACKEND_WARNINGS=1.`,
-    );
-  }
-}
-
-/**
- * Open a store using the env-configured (or auto-detected) backend and path.
- * Returns the concrete store class (cast to IEngramStore at call sites
- * that need the async contract; SQLite callers can keep the concrete class
- * to retain access to SQLite-specific methods like getDb()).
- *
- * Never fails on backend/disk mismatch — only warns. Existing users
- * upgrading without setting env vars get auto-detect; users on the legacy
- * `memory.db` keep working without touching anything.
- */
-export async function openStore(): Promise<{
-  store: IEngramStore;
-  backend: StoreBackend;
-  path: string;
-}> {
-  const backend = getConfiguredBackend();
-  const path = getConfiguredPath();
-
-  warnIfBackendDisagreesWithDisk(backend, path);
-
-  if (backend === 'pglite') {
-    const { PGliteEngramStore } = await import('./pglite.js');
-    const store = new PGliteEngramStore(path);
-    await store.ready();
-    return { store: store as unknown as IEngramStore, backend, path };
-  }
-
-  const { EngramStore } = await import('./sqlite.js');
-  const store = new EngramStore(path);
-  return { store: store as unknown as IEngramStore, backend, path };
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Storage backend factory.
+ *
+ * Picks between SQLite (mature, full features) and PGlite (portable, async,
+ * pgvector). Both backends satisfy the IEngramStore contract — the cognitive
+ * engines work with either through `await`.
+ *
+ *   AWM_STORE_BACKEND=sqlite  — better-sqlite3 + FTS5 + BLOB embeddings
+ *   AWM_STORE_BACKEND=pglite  — PGlite + pgvector + tsvector
+ *
+ * **Backend selection (v0.8.5):** auto-detect on disk when the env var is
+ * unset, so upgrading users on existing `memory.db` files keep working
+ * without setting anything. Order of precedence:
+ *
+ *   1. `AWM_STORE_BACKEND` env var (explicit override — always wins).
+ *   2. Auto-detect: if `memory-pglite/` exists on disk → pglite.
+ *   3. Auto-detect: else if `memory.db` exists on disk → sqlite.
+ *   4. Fall back to sqlite (the default for fresh installs).
+ *
+ * If `AWM_STORE_BACKEND` is set but the on-disk state disagrees (e.g. env
+ * says pglite but only `memory.db` is present), `openStore` prints a one-line
+ * warning suggesting `awm migrate`. The env var still wins — we never
+ * silently switch backends behind the user's back.
+ *
+ * The `AWM_DB_PATH` env var carries the file path (SQLite) or directory
+ * path (PGlite). When unset, default is `memory.db` (sqlite) or
+ * `memory-pglite/` (pglite).
+ *
+ * **Feature parity gaps** (see `docs/pglite-feature-parity.md`):
+ * a few legacy code paths reach for SQLite-specific methods
+ * (coordination plugin needs `store.getDb()`, slim-cache warming, hot
+ * backups). PGlite-backed AWM is fully functional for the cognitive
+ * engines (write, recall, consolidation, retraction, eviction). Opt-in
+ * `AWM_STORE_BACKEND=pglite` skips the SQLite-only extras.
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import type { IEngramStore } from './store.js';
+
+export type StoreBackend = 'sqlite' | 'pglite';
+
+/**
+ * Auto-detect the backend from on-disk state. Used when `AWM_STORE_BACKEND`
+ * is unset. Looks in the current working directory; honors `AWM_DB_PATH`
+ * if it points at a known shape.
+ */
+function detectBackendFromDisk(): StoreBackend | null {
+  // If AWM_DB_PATH is set, infer from its shape.
+  const explicitPath = process.env.AWM_DB_PATH;
+  if (explicitPath && existsSync(explicitPath)) {
+    try {
+      const stat = statSync(explicitPath);
+      if (stat.isDirectory()) return 'pglite'; // PGlite uses a directory
+      if (stat.isFile()) return 'sqlite';      // SQLite is a single file
+    } catch { /* fall through */ }
+  }
+
+  // Otherwise look for the conventional defaults in cwd.
+  // PGlite directory wins over SQLite file when both exist — assume the
+  // user actively migrated and forgot to set the env var. We warn below.
+  if (existsSync('memory-pglite')) return 'pglite';
+  if (existsSync('memory.db')) return 'sqlite';
+  return null;
+}
+
+export function getConfiguredBackend(): StoreBackend {
+  const raw = process.env.AWM_STORE_BACKEND;
+  if (raw !== undefined && raw !== '') {
+    const normalized = raw.toLowerCase();
+    if (normalized === 'pglite') return 'pglite';
+    if (normalized === 'sqlite') return 'sqlite';
+    console.warn(`Unknown AWM_STORE_BACKEND=${raw}; falling back to sqlite`);
+    return 'sqlite';
+  }
+  // Env unset → auto-detect from on-disk state.
+  const detected = detectBackendFromDisk();
+  return detected ?? 'sqlite';
+}
+
+export function getConfiguredPath(): string {
+  if (process.env.AWM_DB_PATH) return process.env.AWM_DB_PATH;
+  return getConfiguredBackend() === 'pglite' ? 'memory-pglite' : 'memory.db';
+}
+
+/**
+ * Print a one-line warning to stderr when the configured backend disagrees
+ * with what's actually on disk. We never fail or silently switch backends
+ * — the explicit configuration always wins. The warning helps users notice
+ * that they may have stranded data on the other backend.
+ */
+function warnIfBackendDisagreesWithDisk(backend: StoreBackend, path: string): void {
+  if (process.env.AWM_SUPPRESS_BACKEND_WARNINGS === '1') return;
+
+  // Only warn when env var was explicit (auto-detect already follows disk).
+  if (!process.env.AWM_STORE_BACKEND) return;
+
+  const otherPath = backend === 'pglite' ? 'memory.db' : 'memory-pglite';
+  const otherBackend = backend === 'pglite' ? 'sqlite' : 'pglite';
+
+  // The "real" check: configured target doesn't exist yet (fresh / empty) AND
+  // the other backend's conventional file exists with data. Likely stranded.
+  const configuredExists = existsSync(path);
+  const otherExists = existsSync(otherPath);
+
+  if (!configuredExists && otherExists) {
+    console.warn(
+      `[awm] AWM_STORE_BACKEND=${backend} but no data at "${path}". ` +
+      `Existing ${otherBackend} data at "${otherPath}" — run \`awm migrate\` ` +
+      `to convert it to ${backend}, or unset AWM_STORE_BACKEND to use ${otherBackend}. ` +
+      `Suppress with AWM_SUPPRESS_BACKEND_WARNINGS=1.`,
+    );
+  }
+}
+
+/**
+ * Open a store using the env-configured (or auto-detected) backend and path.
+ * Returns the concrete store class (cast to IEngramStore at call sites
+ * that need the async contract; SQLite callers can keep the concrete class
+ * to retain access to SQLite-specific methods like getDb()).
+ *
+ * Never fails on backend/disk mismatch — only warns. Existing users
+ * upgrading without setting env vars get auto-detect; users on the legacy
+ * `memory.db` keep working without touching anything.
+ */
+export async function openStore(): Promise<{
+  store: IEngramStore;
+  backend: StoreBackend;
+  path: string;
+}> {
+  const backend = getConfiguredBackend();
+  const path = getConfiguredPath();
+
+  warnIfBackendDisagreesWithDisk(backend, path);
+
+  if (backend === 'pglite') {
+    const { PGliteEngramStore } = await import('./pglite.js');
+    const store = new PGliteEngramStore(path);
+    await store.ready();
+    return { store: store as unknown as IEngramStore, backend, path };
+  }
+
+  const { EngramStore } = await import('./sqlite.js');
+  const store = new EngramStore(path);
+  return { store: store as unknown as IEngramStore, backend, path };
+}

package/src/storage/index.ts

@@ -1,3 +1,3 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-export * from './sqlite.js';
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+export * from './sqlite.js';