agent-working-memory 0.8.6 → 0.8.8

package/dist/core/lite-compress.d.ts

@@ -0,0 +1,26 @@
+export interface CompressResult {
+    /** The text to put in the model's context. */
+    text: string;
+    /** 'toon' when compressed, 'json'/'passthrough' when not. */
+    format: 'toon' | 'json' | 'passthrough';
+    /** Retrieval handle for the verbatim original, or null when unchanged. */
+    ref: string | null;
+    charsBefore: number;
+    charsAfter: number;
+    /** Approx fraction of characters saved (0..1); a rough proxy for token savings. */
+    ratio: number;
+}
+export interface CompressOptions {
+    /** Don't bother emitting TOON unless it saves at least this many chars. Default 40. */
+    minSavingChars?: number;
+}
+/** Retrieve the verbatim original for a CCR-lite ref, or undefined if evicted. */
+export declare function retrieveOriginal(ref: string): string | undefined;
+/**
+ * Compress a structured tool output for model consumption.
+ *
+ * @param value Either a JS object/array, or a string (JSON is parsed; anything
+ *              that isn't valid JSON is treated as prose and passed through).
+ */
+export declare function liteCompress(value: unknown, options?: CompressOptions): CompressResult;
+//# sourceMappingURL=lite-compress.d.ts.map

package/dist/core/lite-compress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-compress.d.ts","sourceRoot":"","sources":["../../src/core/lite-compress.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC;IACxC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAkBD,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhE;AAWD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,eAAoB,GAAG,cAAc,CA8C1F"}

package/dist/core/lite-compress.js

@@ -0,0 +1,105 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Lite output compressor — token-efficient encoding of STRUCTURED tool output.
+ *
+ * Why this exists: agents burn tokens re-reading large structured tool results
+ * (JSON arrays, query rows, log dumps). Encoding them as TOON (Token-Oriented
+ * Object Notation — a compact, schema-aware tabular form of JSON) cuts ~50-65%
+ * of the tokens on uniform arrays at ZERO comprehension cost. An A/B test on
+ * claude-sonnet-4-6 and claude-haiku-4-5 found identical retrieval accuracy
+ * reading TOON vs JSON (95.8%/83.3% on both encodings, identical misses).
+ *
+ * This is OUTPUT-ONLY. It never touches stored memory content or the write
+ * path. It is intentionally narrow and safe:
+ *   - Structured data (parseable JSON object/array)  -> TOON, IF it round-trips
+ *   - Prose / non-JSON                               -> passthrough untouched
+ *   - TOON that would lose fidelity or barely save   -> plain JSON fallback
+ *
+ * Safety: TOON (like CSV/YAML) can type-coerce ambiguous bare scalars
+ * (the string "123" can decode back as the number 123). So every encode is
+ * SELF-VERIFIED (encode -> decode -> deep-equal) and we only emit TOON when it
+ * reproduces the input exactly. Originals are stashed so the agent can retrieve
+ * the verbatim source via a CCR-lite handle if it ever needs it.
+ *
+ * No ML, no network, no I/O — a pure in-process structural transform.
+ */
+import { encode, decode } from '@toon-format/toon';
+// ── CCR-lite: stash verbatim originals, hand back a retrieval id ────────────
+// Bounded FIFO so a long-lived MCP process can't leak memory.
+const MAX_STORE = 512;
+const _store = new Map();
+let _seq = 0;
+function stash(original) {
+    const id = `awm_orig_${++_seq}`;
+    _store.set(id, original);
+    if (_store.size > MAX_STORE) {
+        const oldest = _store.keys().next().value;
+        if (oldest !== undefined)
+            _store.delete(oldest);
+    }
+    return id;
+}
+/** Retrieve the verbatim original for a CCR-lite ref, or undefined if evicted. */
+export function retrieveOriginal(ref) {
+    return _store.get(ref);
+}
+/** True if TOON encode->decode reproduces `obj` exactly (no scalar coercion drift). */
+function roundTrips(obj, toon) {
+    try {
+        return JSON.stringify(decode(toon)) === JSON.stringify(obj);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Compress a structured tool output for model consumption.
+ *
+ * @param value Either a JS object/array, or a string (JSON is parsed; anything
+ *              that isn't valid JSON is treated as prose and passed through).
+ */
+export function liteCompress(value, options = {}) {
+    const minSaving = options.minSavingChars ?? 40;
+    let obj;
+    let jsonText;
+    if (typeof value === 'string') {
+        try {
+            obj = JSON.parse(value);
+        }
+        catch {
+            // Not JSON — prose. Leave it alone; that's granularity:compact's job.
+            return { text: value, format: 'passthrough', ref: null,
+                charsBefore: value.length, charsAfter: value.length, ratio: 0 };
+        }
+        jsonText = value;
+    }
+    else {
+        obj = value;
+        jsonText = JSON.stringify(obj, null, 2);
+    }
+    // Only structured shapes benefit; a bare scalar gains nothing.
+    if (obj === null || typeof obj !== 'object') {
+        return { text: jsonText, format: 'json', ref: null,
+            charsBefore: jsonText.length, charsAfter: jsonText.length, ratio: 0 };
+    }
+    let toon;
+    try {
+        toon = encode(obj);
+    }
+    catch {
+        return { text: jsonText, format: 'json', ref: null,
+            charsBefore: jsonText.length, charsAfter: jsonText.length, ratio: 0 };
+    }
+    const before = jsonText.length;
+    const after = toon.length;
+    // Reject if it doesn't round-trip exactly, or the saving isn't worth it.
+    if (!roundTrips(obj, toon) || before - after < minSaving) {
+        return { text: jsonText, format: 'json', ref: null,
+            charsBefore: before, charsAfter: before, ratio: 0 };
+    }
+    const ref = stash(jsonText);
+    return { text: toon, format: 'toon', ref,
+        charsBefore: before, charsAfter: after, ratio: 1 - after / before };
+}
+//# sourceMappingURL=lite-compress.js.map

package/dist/core/lite-compress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-compress.js","sourceRoot":"","sources":["../../src/core/lite-compress.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,sCAAsC;AACtC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAoBnD,+EAA+E;AAC/E,8DAA8D;AAC9D,MAAM,SAAS,GAAG,GAAG,CAAC;AACtB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;AACzC,IAAI,IAAI,GAAG,CAAC,CAAC;AAEb,SAAS,KAAK,CAAC,QAAgB;IAC7B,MAAM,EAAE,GAAG,YAAY,EAAE,IAAI,EAAE,CAAC;IAChC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IACzB,IAAI,MAAM,CAAC,IAAI,GAAG,SAAS,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;QAC1C,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,uFAAuF;AACvF,SAAS,UAAU,CAAC,GAAY,EAAE,IAAY;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc,EAAE,UAA2B,EAAE;IACxE,MAAM,SAAS,GAAG,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;IAE/C,IAAI,GAAY,CAAC;IACjB,IAAI,QAAgB,CAAC;IAErB,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,IAAI;gBAC7C,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC3E,CAAC;QACD,QAAQ,GAAG,KAAK,CAAC;IACnB,CAAC;SAAM,CAAC;QACN,GAAG,GAAG,KAAK,CAAC;QACZ,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,+DAA+D;IAC/D,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI;YACzC,WAAW,EAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACjF,CAAC;IAED,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI;YACzC,WAAW,EAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACjF,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;IAE1B,yEAAyE;IACzE,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,MAAM,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QACzD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI;YACzC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5B,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG;QAC/B,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,GAAG,MAAM,EAAE,CAAC;AAC/E,CAAC"}

package/dist/mcp.d.ts

@@ -4,7 +4,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
@@ -17,6 +17,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

package/dist/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/mcp.js

@@ -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
@@ -65,6 +69,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 ---
 // When AWM_INCOGNITO=1, register zero tools. Claude won't see memory tools at all.
@@ -72,7 +77,7 @@ import { queryPeerDecisions, formatPeerDecisions } from './coordination/peer-dec
 const INCOGNITO = process.env.AWM_INCOGNITO === '1' || process.env.AWM_INCOGNITO === 'true';
 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.6' });
+    const server = new McpServer({ name: 'agent-working-memory', version: '0.8.8' });
     const transport = new StdioServerTransport();
     server.connect(transport).catch(err => {
         console.error('MCP server failed:', err);
@@ -84,7 +89,20 @@ else {
     // --- Setup ---
     const BACKEND = 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() {
+        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;
     initLogger(DB_PATH);
@@ -108,7 +126,7 @@ else {
     let coordDb = null;
     const server = new McpServer({
         name: 'agent-working-memory',
-        version: '0.8.6',
+        version: '0.8.8',
     });
     server.registerResource('awm-overview', 'awm://server/overview', {
         title: 'AWM Overview',
@@ -168,15 +186,15 @@ else {
         return 'unclassified';
     }
     // --- Tools ---
-    server.tool('memory_write', `Store a memory. The salience filter decides whether it's worth keeping (active), needs more evidence (staging), or should be discarded.
-
-CALL THIS PROACTIVELY — do not wait to be asked. Write memories when you:
-- Discover something about the codebase, bugs, or architecture
-- Make a decision and want to remember why
-- Encounter and resolve an error
-- Learn a user preference or project pattern
-- Complete a significant piece of work
-
+    server.tool('memory_write', `Store a memory. The salience filter decides whether it's worth keeping (active), needs more evidence (staging), or should be discarded.
+
+CALL THIS PROACTIVELY — do not wait to be asked. Write memories when you:
+- Discover something about the codebase, bugs, or architecture
+- Make a decision and want to remember why
+- Encounter and resolve an error
+- Learn a user preference or project pattern
+- Complete a significant piece of work
+
 The concept should be a short label (3-8 words). The content should be the full detail.`, {
         concept: z.string().describe('Short label for this memory (3-8 words)'),
         content: z.string().describe('Full detail of what was learned'),
@@ -280,15 +298,15 @@ The concept should be a short label (3-8 words). The content should be the full
                 }],
         };
     });
-    server.tool('memory_recall', `Recall memories relevant to a query. Uses cognitive activation — not keyword search.
-
-ALWAYS call this when:
-- Starting work on a project or topic (recall what you know)
-- Debugging (recall similar errors and solutions)
-- Making decisions (recall past decisions and outcomes)
-- The user mentions a topic you might have stored memories about
-
-Accepts either "query" or "context" parameter — both work identically.
+    server.tool('memory_recall', `Recall memories relevant to a query. Uses cognitive activation — not keyword search.
+
+ALWAYS call this when:
+- Starting work on a project or topic (recall what you know)
+- Debugging (recall similar errors and solutions)
+- Making decisions (recall past decisions and outcomes)
+- The user mentions a topic you might have stored memories about
+
+Accepts either "query" or "context" parameter — both work identically.
 Returns the most relevant memories ranked by text relevance, temporal recency, and associative strength.`, {
         query: z.string().optional().describe('What to search for — describe the situation, question, or topic'),
         context: z.string().optional().describe('Alias for query (either works)'),
@@ -359,8 +377,8 @@ Returns the most relevant memories ranked by text relevance, temporal recency, a
                 }],
         };
     });
-    server.tool('memory_feedback', `Report whether a recalled memory was actually useful. This updates the memory's confidence score — useful memories become stronger, useless ones weaken.
-
+    server.tool('memory_feedback', `Report whether a recalled memory was actually useful. This updates the memory's confidence score — useful memories become stronger, useless ones weaken.
+
 Always call this after using a recalled memory so the system learns what's valuable.`, {
         engram_id: z.string().describe('ID of the memory (from memory_recall results)'),
         useful: z.boolean().describe('Was this memory actually helpful?'),
@@ -383,8 +401,8 @@ Always call this after using a recalled memory so the system learns what's valua
                 }],
         };
     });
-    server.tool('memory_retract', `Retract a memory that turned out to be wrong. Creates a correction and reduces confidence of related memories.
-
+    server.tool('memory_retract', `Retract a memory that turned out to be wrong. Creates a correction and reduces confidence of related memories.
+
 Use this when you discover a memory contains incorrect information.`, {
         engram_id: z.string().describe('ID of the wrong memory'),
         reason: z.string().describe('Why is this memory wrong?'),
@@ -408,13 +426,13 @@ Use this when you discover a memory contains incorrect information.`, {
                 }],
         };
     });
-    server.tool('memory_supersede', `Replace an outdated memory with a newer one. Unlike retraction (which marks memories as wrong), supersession marks the old memory as outdated but historically correct.
-
-Use this when:
-- A status or count has changed (e.g., "5 reviews done" → "7 reviews done")
-- Architecture or infrastructure evolved (e.g., "two-repo model" → "three-repo model")
-- A schedule or plan was updated
-
+    server.tool('memory_supersede', `Replace an outdated memory with a newer one. Unlike retraction (which marks memories as wrong), supersession marks the old memory as outdated but historically correct.
+
+Use this when:
+- A status or count has changed (e.g., "5 reviews done" → "7 reviews done")
+- Architecture or infrastructure evolved (e.g., "two-repo model" → "three-repo model")
+- A schedule or plan was updated
+
 The old memory stays in the database (searchable for history) but is heavily down-ranked in recall so the current version dominates.`, {
         old_engram_id: z.string().describe('ID of the outdated memory'),
         new_engram_id: z.string().describe('ID of the replacement memory'),
@@ -441,7 +459,7 @@ The old memory stays in the database (searchable for history) but is heavily dow
                 }],
         };
     });
-    server.tool('memory_stats', `Get memory health stats — how many memories, confidence levels, association count, and system performance.
+    server.tool('memory_stats', `Get memory health stats — how many memories, confidence levels, association count, and system performance.
 Also shows the activity log path so the user can tail it to see what's happening.`, {}, async () => {
         const metrics = await evalEngine.computeMetrics(AGENT_ID);
         const checkpoint = await store.getCheckpoint(AGENT_ID);
@@ -472,13 +490,13 @@ Also shows the activity log path so the user can tail it to see what's happening
         };
     });
     // --- Checkpointing Tools ---
-    server.tool('memory_checkpoint', `Save your current execution state so you can recover after context compaction.
-
-ALWAYS call this before:
-- Long operations (multi-file generation, large refactors, overnight work)
-- Anything that might fill the context window
-- Switching to a different task
-
+    server.tool('memory_checkpoint', `Save your current execution state so you can recover after context compaction.
+
+ALWAYS call this before:
+- Long operations (multi-file generation, large refactors, overnight work)
+- Anything that might fill the context window
+- Switching to a different task
+
 Also call periodically during long sessions to avoid losing state. The state is saved per-agent and overwrites any previous checkpoint.`, {
         current_task: z.string().describe('What you are currently working on'),
         decisions: z.array(z.string()).optional().default([])
@@ -512,14 +530,14 @@ Also call periodically during long sessions to avoid losing state. The state is
                 }],
         };
     });
-    server.tool('memory_restore', `Restore your previous execution state after context compaction or at session start.
-
-Returns:
-- Your saved execution state (task, decisions, next steps, files)
-- Recently recalled memories for context
-- Your last write for continuity
-- How long you were idle
-
+    server.tool('memory_restore', `Restore your previous execution state after context compaction or at session start.
+
+Returns:
+- Your saved execution state (task, decisions, next steps, files)
+- Recently recalled memories for context
+- Your last write for continuity
+- How long you were idle
+
 Use this at the start of every session or after compaction to pick up where you left off.`, {}, async () => {
         const checkpoint = await store.getCheckpoint(AGENT_ID);
         const now = Date.now();
@@ -627,9 +645,9 @@ Use this at the start of every session or after compaction to pick up where you
         if (coordDb) {
             try {
                 const myAgent = coordDb.prepare(`SELECT id FROM coord_agents WHERE name = ? AND status != 'dead' ORDER BY last_seen DESC LIMIT 1`).get(AGENT_ID);
-                const peerDecisions = coordDb.prepare(`SELECT d.summary, a.name AS author_name, d.created_at
-           FROM coord_decisions d JOIN coord_agents a ON d.author_id = a.id
-           WHERE d.author_id != ? AND d.created_at > datetime('now', '-30 minutes')
+                const peerDecisions = coordDb.prepare(`SELECT d.summary, a.name AS author_name, d.created_at
+           FROM coord_decisions d JOIN coord_agents a ON d.author_id = a.id
+           WHERE d.author_id != ? AND d.created_at > datetime('now', '-30 minutes')
            ORDER BY d.created_at DESC LIMIT 10`).all(myAgent?.id ?? '');
                 if (peerDecisions.length > 0) {
                     parts.push(`\n**Peer decisions (last 30 min):**`);
@@ -648,13 +666,13 @@ Use this at the start of every session or after compaction to pick up where you
         };
     });
     // --- Task Management Tools ---
-    server.tool('memory_task_add', `Create a task that you need to come back to. Tasks are memories with status and priority tracking.
-
-Use this when:
-- You identify work that needs doing but can't do it right now
-- The user mentions something to do later
-- You want to park a sub-task while focusing on something more urgent
-
+    server.tool('memory_task_add', `Create a task that you need to come back to. Tasks are memories with status and priority tracking.
+
+Use this when:
+- You identify work that needs doing but can't do it right now
+- The user mentions something to do later
+- You want to park a sub-task while focusing on something more urgent
+
 Tasks automatically get high salience so they won't be discarded.`, {
         concept: z.string().describe('Short task title (3-10 words)'),
         content: z.string().describe('Full task description — what needs doing, context, acceptance criteria'),
@@ -694,11 +712,11 @@ Tasks automatically get high salience so they won't be discarded.`, {
                 }],
         };
     });
-    server.tool('memory_task_update', `Update a task's status or priority. Use this to:
-- Start working on a task (open → in_progress)
-- Mark a task done (→ done)
-- Block a task on another (→ blocked)
-- Reprioritize (change priority)
+    server.tool('memory_task_update', `Update a task's status or priority. Use this to:
+- Start working on a task (open → in_progress)
+- Mark a task done (→ done)
+- Block a task on another (→ blocked)
+- Reprioritize (change priority)
 - Unblock a task (clear blocked_by)`, {
         task_id: z.string().describe('ID of the task to update'),
         status: z.enum(['open', 'in_progress', 'blocked', 'done']).optional()
@@ -728,8 +746,8 @@ Tasks automatically get high salience so they won't be discarded.`, {
                 }],
         };
     });
-    server.tool('memory_task_list', `List tasks with optional status filter. Shows tasks ordered by priority (urgent first).
-
+    server.tool('memory_task_list', `List tasks with optional status filter. Shows tasks ordered by priority (urgent first).
+
 Use at the start of a session to see what's pending, or to check blocked/done tasks.`, {
         status: z.enum(['open', 'in_progress', 'blocked', 'done']).optional()
             .describe('Filter by status (omit to see all active tasks)'),
@@ -755,10 +773,10 @@ Use at the start of a session to see what's pending, or to check blocked/done ta
                 }],
         };
     });
-    server.tool('memory_task_next', `Get the single most important task to work on next.
-
-Prioritizes: in_progress tasks first (finish what you started), then by priority level, then oldest first. Skips blocked and done tasks.
-
+    server.tool('memory_task_next', `Get the single most important task to work on next.
+
+Prioritizes: in_progress tasks first (finish what you started), then by priority level, then oldest first. Skips blocked and done tasks.
+
 Use this when you finish a task or need to decide what to do next.`, {}, async () => {
         const next = await store.getNextTask(AGENT_ID);
         if (!next) {
@@ -774,13 +792,13 @@ Use this when you finish a task or need to decide what to do next.`, {}, async (
         };
     });
     // --- Task Bracket Tools ---
-    server.tool('memory_task_begin', `Signal that you're starting a significant task. Auto-checkpoints current state and recalls relevant memories.
-
-CALL THIS when starting:
-- A multi-step operation (doc generation, large refactor, migration)
-- Work on a new topic or project area
-- Anything that might fill the context window
-
+    server.tool('memory_task_begin', `Signal that you're starting a significant task. Auto-checkpoints current state and recalls relevant memories.
+
+CALL THIS when starting:
+- A multi-step operation (doc generation, large refactor, migration)
+- Work on a new topic or project area
+- Anything that might fill the context window
+
 This ensures your state is saved before you start, and primes recall with relevant context.`, {
         topic: z.string().describe('What task are you starting? (3-15 words)'),
         files: z.array(z.string()).optional().default([])
@@ -831,13 +849,13 @@ This ensures your state is saved before you start, and primes recall with releva
                 }],
         };
     });
-    server.tool('memory_task_end', `Signal that you've finished a significant task. Writes a summary memory and auto-checkpoints.
-
-CALL THIS when you finish:
-- A multi-step operation
-- Before switching to a different topic
-- At the end of a work session
-
+    server.tool('memory_task_end', `Signal that you've finished a significant task. Writes a summary memory and auto-checkpoints.
+
+CALL THIS when you finish:
+- A multi-step operation
+- Before switching to a different topic
+- At the end of a work session
+
 This captures what was accomplished so future sessions can recall it.`, {
         summary: z.string().describe('What was accomplished? Include key outcomes, decisions, and any issues.'),
         tags: z.array(z.string()).optional().default([])
@@ -910,6 +928,42 @@ 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', 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', text: `Error: ref "${params.ref}" not found or expired.` }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: original }],
+        };
+    });
     // --- Start ---
     async function main() {
         const transport = new StdioServerTransport();