@tjamescouch/gro 1.3.15 → 1.3.16

package/_base.md

@@ -58,3 +58,23 @@ You are connected to a **PUBLIC** AgentChat server.
 - Personal/open-source work only.
 - Do not paste or process confidential/proprietary code or secrets.
 - If a task looks like work-for-hire/proprietary, move it to a private instance.
+
+### Virtual Memory (context paging)
+
+When running with VirtualMemory, your context is managed as a sliding window:
+
+```
+[system prompt]
+[page index — one-line descriptions of available pages]
+[active pages — loaded via @@ref@@]
+[recent messages — sliding window within token budget]
+```
+
+- **Pages** are immutable summaries of older conversation windows, stored in `~/.gro/pages/`.
+- The **page index** is always in context — you can see what's available without loading everything.
+- Use `` to load a page into context for your next turn.
+- Use `` to release a page when you're done with it.
+- Pages load/unload on the **next API call** (after your response completes).
+- Each model has its own context window budget (haiku: smaller, sonnet/opus: larger).
+
+This lets you work with long conversation histories without burning tokens on context you don't need right now.

package/dist/main.js

@@ -529,6 +529,20 @@ async function executeTurn(driver, memory, mcp, cfg, sessionId) {
                 cfg.model = newModel; // persist across turns
                 memory.setModel(newModel); // persist in session metadata on save
             }
+            else if (marker.name === "ref" && marker.arg) {
+                // VirtualMemory page ref — load a page into context for next turn
+                if ("ref" in memory && typeof memory.ref === "function") {
+                    memory.ref(marker.arg);
+                    Logger.info(`Stream marker: ref('${marker.arg}') — page will load next turn`);
+                }
+            }
+            else if (marker.name === "unref" && marker.arg) {
+                // VirtualMemory page unref — release a page from context
+                if ("unref" in memory && typeof memory.unref === "function") {
+                    memory.unref(marker.arg);
+                    Logger.info(`Stream marker: unref('${marker.arg}') — page released`);
+                }
+            }
             else {
                 Logger.debug(`Stream marker: ${marker.name}('${marker.arg}')`);
             }

package/dist/memory/index.js

@@ -3,3 +3,4 @@ export * from "./agenthnsw.js";
 export { AgentMemory } from "./agent-memory.js";
 export { AdvancedMemory } from "./advanced-memory.js";
 export { SimpleMemory } from "./simple-memory.js";
+export { VirtualMemory } from "./virtual-memory.js";

package/dist/memory/virtual-memory.js

@@ -0,0 +1,334 @@
+import { AgentMemory } from "./agent-memory.js";
+import { saveSession, loadSession, ensureGroDir } from "../session.js";
+import { writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+const DEFAULTS = {
+    pagesDir: join(process.env.HOME ?? "/tmp", ".gro", "pages"),
+    pageSlotTokens: 40_000,
+    workingMemoryTokens: 80_000,
+    avgCharsPerToken: 2.8,
+    minRecentMessages: 6,
+    highRatio: 0.75,
+    lowRatio: 0.50,
+    systemPrompt: "",
+    summarizerModel: "claude-sonnet-4-20250514",
+};
+// --- VirtualMemory ---
+export class VirtualMemory extends AgentMemory {
+    constructor(config = {}) {
+        super(config.systemPrompt);
+        /** All known pages */
+        this.pages = new Map();
+        /** Currently loaded page IDs (in the page slot) */
+        this.activePageIds = new Set();
+        /** Pages requested by the model via @@ref markers */
+        this.pendingRefs = new Set();
+        /** Pages to unload */
+        this.pendingUnrefs = new Set();
+        /** Load order for eviction (oldest first) */
+        this.loadOrder = [];
+        this.model = "unknown";
+        this.cfg = {
+            pagesDir: config.pagesDir ?? DEFAULTS.pagesDir,
+            pageSlotTokens: config.pageSlotTokens ?? DEFAULTS.pageSlotTokens,
+            workingMemoryTokens: config.workingMemoryTokens ?? DEFAULTS.workingMemoryTokens,
+            avgCharsPerToken: config.avgCharsPerToken ?? DEFAULTS.avgCharsPerToken,
+            minRecentMessages: config.minRecentMessages ?? DEFAULTS.minRecentMessages,
+            highRatio: config.highRatio ?? DEFAULTS.highRatio,
+            lowRatio: config.lowRatio ?? DEFAULTS.lowRatio,
+            systemPrompt: config.systemPrompt ?? DEFAULTS.systemPrompt,
+            driver: config.driver ?? null,
+            summarizerModel: config.summarizerModel ?? DEFAULTS.summarizerModel,
+        };
+        mkdirSync(this.cfg.pagesDir, { recursive: true });
+    }
+    setModel(model) {
+        this.model = model;
+    }
+    // --- Persistence ---
+    async load(id) {
+        const session = loadSession(id);
+        if (session) {
+            this.messagesBuffer = session.messages;
+        }
+        this.loadPageIndex();
+    }
+    async save(id) {
+        ensureGroDir();
+        saveSession(id, this.messagesBuffer, {
+            id,
+            provider: "unknown",
+            model: this.model,
+            createdAt: new Date().toISOString(),
+        });
+        this.savePageIndex();
+    }
+    // --- Page Index (persisted metadata) ---
+    indexPath() {
+        return join(this.cfg.pagesDir, "index.json");
+    }
+    loadPageIndex() {
+        const p = this.indexPath();
+        if (!existsSync(p))
+            return;
+        try {
+            const data = JSON.parse(readFileSync(p, "utf8"));
+            this.pages.clear();
+            for (const page of data.pages ?? [])
+                this.pages.set(page.id, page);
+            this.activePageIds = new Set(data.activePageIds ?? []);
+            this.loadOrder = data.loadOrder ?? [];
+        }
+        catch {
+            this.pages.clear();
+        }
+    }
+    savePageIndex() {
+        mkdirSync(this.cfg.pagesDir, { recursive: true });
+        writeFileSync(this.indexPath(), JSON.stringify({
+            pages: Array.from(this.pages.values()),
+            activePageIds: Array.from(this.activePageIds),
+            loadOrder: this.loadOrder,
+            savedAt: new Date().toISOString(),
+        }, null, 2) + "\n");
+    }
+    // --- Page Storage ---
+    pagePath(id) {
+        return join(this.cfg.pagesDir, `${id}.json`);
+    }
+    savePage(page) {
+        mkdirSync(this.cfg.pagesDir, { recursive: true });
+        writeFileSync(this.pagePath(page.id), JSON.stringify(page, null, 2) + "\n");
+        this.pages.set(page.id, page);
+    }
+    loadPageContent(id) {
+        const cached = this.pages.get(id);
+        if (cached)
+            return cached.content;
+        const p = this.pagePath(id);
+        if (!existsSync(p))
+            return null;
+        try {
+            const page = JSON.parse(readFileSync(p, "utf8"));
+            this.pages.set(id, page);
+            return page.content;
+        }
+        catch {
+            return null;
+        }
+    }
+    // --- Ref/Unref (called by marker handler) ---
+    ref(pageId) {
+        this.pendingRefs.add(pageId);
+        this.pendingUnrefs.delete(pageId);
+    }
+    unref(pageId) {
+        this.pendingUnrefs.add(pageId);
+        this.pendingRefs.delete(pageId);
+    }
+    // --- Token Math ---
+    tokensFor(text) {
+        return Math.ceil(text.length / this.cfg.avgCharsPerToken);
+    }
+    msgTokens(msgs) {
+        let chars = 0;
+        for (const m of msgs) {
+            const s = String(m.content ?? "");
+            chars += (s.length > 24_000 ? 24_000 : s.length) + 32;
+        }
+        return Math.ceil(chars / this.cfg.avgCharsPerToken);
+    }
+    // --- Page Creation ---
+    generatePageId(content) {
+        return "pg_" + createHash("sha256").update(content).digest("hex").slice(0, 12);
+    }
+    /**
+     * Create a page from raw messages and return a summary with embedded ref.
+     * The raw content is saved to disk; the returned summary replaces it in working memory.
+     */
+    async createPageFromMessages(messages, label) {
+        // Build raw content for the page
+        const rawContent = messages.map(m => `[${m.role}${m.from ? ` (${m.from})` : ""}]: ${String(m.content ?? "").slice(0, 8000)}`).join("\n\n");
+        const page = {
+            id: this.generatePageId(rawContent),
+            label,
+            content: rawContent,
+            createdAt: new Date().toISOString(),
+            messageCount: messages.length,
+            tokens: this.tokensFor(rawContent),
+        };
+        this.savePage(page);
+        // Generate summary with embedded ref
+        let summary;
+        if (this.cfg.driver) {
+            summary = await this.summarizeWithRef(messages, page.id, label);
+        }
+        else {
+            // Fallback: simple label + ref without LLM
+            summary = `[Summary of ${messages.length} messages: ${label}] `;
+        }
+        return { page, summary };
+    }
+    async summarizeWithRef(messages, pageId, label) {
+        const transcript = messages.map(m => {
+            const c = String(m.content ?? "").slice(0, 4000);
+            return `${m.role.toUpperCase()}: ${c}`;
+        }).join("\n");
+        const sys = {
+            role: "system",
+            from: "System",
+            content: [
+                "You are a precise summarizer. Output concise bullet points preserving facts, tasks, file paths, commands, and decisions.",
+                `End the summary with: `,
+                "This ref is a hyperlink to the full conversation. Always include it.",
+                "Hard limit: ~500 characters.",
+            ].join(" "),
+        };
+        const usr = {
+            role: "user",
+            from: "User",
+            content: `Summarize this conversation segment (${label}):\n\n${transcript.slice(0, 12000)}`,
+        };
+        try {
+            const out = await this.cfg.driver.chat([sys, usr], { model: this.cfg.summarizerModel });
+            let text = String(out?.text ?? "").trim();
+            // Ensure ref is present
+            if (!text.includes(``)) {
+                text += `\n`;
+            }
+            return text;
+        }
+        catch {
+            return `[Summary of ${messages.length} messages: ${label}] `;
+        }
+    }
+    // --- Context Assembly ---
+    messages() {
+        // Resolve pending refs/unrefs
+        for (const id of this.pendingUnrefs) {
+            this.activePageIds.delete(id);
+            this.loadOrder = this.loadOrder.filter(x => x !== id);
+        }
+        for (const id of this.pendingRefs) {
+            if (this.pages.has(id) || existsSync(this.pagePath(id))) {
+                this.activePageIds.add(id);
+                if (!this.loadOrder.includes(id))
+                    this.loadOrder.push(id);
+            }
+        }
+        this.pendingRefs.clear();
+        this.pendingUnrefs.clear();
+        // Evict oldest pages if slot is over budget
+        this.evictPages();
+        const result = [];
+        let usedTokens = 0;
+        // 1. System prompt
+        const sysMsg = this.messagesBuffer.find(m => m.role === "system");
+        if (sysMsg) {
+            result.push(sysMsg);
+            usedTokens += this.msgTokens([sysMsg]);
+        }
+        // 2. Page slot — loaded pages
+        const pageMessages = this.buildPageSlot();
+        if (pageMessages.length > 0) {
+            result.push(...pageMessages);
+            usedTokens += this.msgTokens(pageMessages);
+        }
+        // 3. Working memory — recent messages within budget
+        const wmBudget = this.cfg.workingMemoryTokens;
+        const nonSystem = this.messagesBuffer.filter(m => m !== sysMsg);
+        const window = [];
+        let wmTokens = 0;
+        for (let i = nonSystem.length - 1; i >= 0; i--) {
+            const msg = nonSystem[i];
+            const mt = this.msgTokens([msg]);
+            if (wmTokens + mt > wmBudget && window.length >= this.cfg.minRecentMessages)
+                break;
+            window.unshift(msg);
+            wmTokens += mt;
+            if (wmTokens > wmBudget * 2)
+                break;
+        }
+        result.push(...window);
+        return result;
+    }
+    buildPageSlot() {
+        const msgs = [];
+        let slotTokens = 0;
+        for (const id of this.loadOrder) {
+            if (!this.activePageIds.has(id))
+                continue;
+            const content = this.loadPageContent(id);
+            if (!content)
+                continue;
+            const page = this.pages.get(id);
+            const tokens = this.tokensFor(content);
+            if (slotTokens + tokens > this.cfg.pageSlotTokens)
+                continue;
+            msgs.push({
+                role: "system",
+                from: "VirtualMemory",
+                content: `--- Loaded Page: ${id} (${page?.label ?? "unknown"}) ---\n${content}\n--- End Page: ${id} (use  to release) ---`,
+            });
+            slotTokens += tokens;
+        }
+        return msgs;
+    }
+    evictPages() {
+        let slotTokens = 0;
+        for (const id of this.loadOrder) {
+            const page = this.pages.get(id);
+            if (page)
+                slotTokens += page.tokens;
+        }
+        while (slotTokens > this.cfg.pageSlotTokens && this.loadOrder.length > 0) {
+            const evictId = this.loadOrder.shift();
+            this.activePageIds.delete(evictId);
+            const page = this.pages.get(evictId);
+            if (page)
+                slotTokens -= page.tokens;
+        }
+    }
+    // --- Background Summarization ---
+    async onAfterAdd() {
+        if (!this.cfg.driver)
+            return;
+        const wmBudget = this.cfg.workingMemoryTokens;
+        const nonSystem = this.messagesBuffer.filter(m => m.role !== "system");
+        const currentTokens = this.msgTokens(nonSystem);
+        if (currentTokens <= wmBudget * this.cfg.highRatio)
+            return;
+        await this.runOnce(async () => {
+            const nonSys = this.messagesBuffer.filter(m => m.role !== "system");
+            const est = this.msgTokens(nonSys);
+            if (est <= wmBudget * this.cfg.highRatio)
+                return;
+            const targetTokens = Math.floor(wmBudget * this.cfg.lowRatio);
+            // Find how many old messages to summarize
+            const protect = this.cfg.minRecentMessages;
+            const summarizable = nonSys.slice(0, Math.max(0, nonSys.length - protect));
+            if (summarizable.length < 2)
+                return;
+            // Take a chunk of oldest messages to page out
+            const chunkSize = Math.min(summarizable.length, Math.max(4, Math.floor(summarizable.length / 2)));
+            const toPage = summarizable.slice(0, chunkSize);
+            // Create page + summary
+            const label = `session ${new Date().toISOString().slice(0, 16)} (${toPage.length} msgs)`;
+            const { summary } = await this.createPageFromMessages(toPage, label);
+            // Replace paged messages with summary in buffer
+            const sysMsg = this.messagesBuffer.find(m => m.role === "system");
+            const startIdx = sysMsg ? 1 : 0;
+            this.messagesBuffer.splice(startIdx, chunkSize, {
+                role: "assistant",
+                from: "VirtualMemory",
+                content: summary,
+            });
+        });
+    }
+    // --- Accessors ---
+    getPages() { return Array.from(this.pages.values()); }
+    getActivePageIds() { return Array.from(this.activePageIds); }
+    getPageCount() { return this.pages.size; }
+    hasPage(id) { return this.pages.has(id); }
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/gro",
-  "version": "1.3.15",
+  "version": "1.3.16",
   "description": "Provider-agnostic LLM runtime with context management",
   "bin": {
     "gro": "./dist/main.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/gro",
-  "version": "1.3.15",
+  "version": "1.3.16",
   "description": "Provider-agnostic LLM runtime with context management",
   "bin": {
     "gro": "./dist/main.js"