clementine-agent 1.2.1 → 1.2.3

package/dist/memory/write-queue.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Async write queue for non-critical memory writes.
+ *
+ * Pattern: 2026-frontier agent memory layers (Mem0, Zep) defer audit and
+ * observability writes off the request thread to keep p95 retrieval latency
+ * low. Mem0 reports ~91% p95 latency reduction with this pattern; voice
+ * agents in particular need it since there's no scrollback to recover.
+ *
+ * Scope: only non-user-visible writes (transcripts, recall traces, outcomes,
+ * access log). User-driven mutations (memory_write, user_model, pinChunk,
+ * updateFile) stay synchronous so the user sees immediate persistence.
+ *
+ * Trade-offs:
+ *  - `recordOutcome` updates `last_outcome_score` which feeds retrieval
+ *    ranking. Async-deferring it means up to one flush interval (~250ms) of
+ *    EMA staleness — acceptable for ranking signal that already smooths.
+ *  - On hard process kill (SIGKILL, OOM) the in-flight queue is lost. Audit
+ *    writes are best-effort by design; existing call sites already swallow
+ *    errors. Drain on SIGTERM/SIGUSR1 covers planned shutdowns.
+ */
+export type QueueOp = {
+    kind: 'transcript-turn';
+    sessionKey: string;
+    role: string;
+    content: string;
+    model: string;
+} | {
+    kind: 'recall';
+    sessionKey: string;
+    messageId: string | null;
+    query: string;
+    chunkIds: number[];
+    scores: number[];
+    agentSlug: string | null;
+} | {
+    kind: 'outcome';
+    outcomes: Array<{
+        chunkId: number;
+        referenced: boolean;
+    }>;
+    sessionKey: string | null;
+} | {
+    kind: 'access';
+    chunkIds: number[];
+    accessType: string;
+};
+export interface WriteQueueOpts {
+    flushIntervalMs?: number;
+    flushSize?: number;
+    /** Hard cap on the buffer to bound memory under write storms. */
+    maxBuffer?: number;
+}
+/**
+ * Minimal write-behind queue for the memory store. Not concurrent-safe at
+ * the JS level — assumes the single-process daemon model that Clementine
+ * already uses for all memory writes.
+ */
+export declare class WriteQueue {
+    private store;
+    private buffer;
+    private timer;
+    private readonly flushIntervalMs;
+    private readonly flushSize;
+    private readonly maxBuffer;
+    private flushing;
+    private dropped;
+    constructor(store: any, opts?: WriteQueueOpts);
+    /** Begin periodic flushing. Idempotent. */
+    start(): void;
+    /** Stop the periodic timer (does not drain). */
+    stop(): void;
+    enqueue(op: QueueOp): void;
+    size(): number;
+    stats(): {
+        size: number;
+        dropped: number;
+    };
+    /**
+     * Apply all queued ops to the store. Ops that fail are logged and skipped;
+     * they don't block the rest of the batch. Concurrent calls collapse — the
+     * second caller exits immediately if a flush is in progress.
+     */
+    flush(): Promise<{
+        flushed: number;
+        errors: number;
+    }>;
+    /**
+     * Stop the timer and flush everything currently buffered. Loops until
+     * the buffer is empty so any ops enqueued during a flush also drain.
+     */
+    drain(): Promise<void>;
+    private apply;
+}
+/** Convenience: install SIGTERM/SIGUSR1 drain hooks on the process. */
+export declare function installShutdownDrain(queue: WriteQueue): void;
+//# sourceMappingURL=write-queue.d.ts.map

package/dist/memory/write-queue.js

@@ -0,0 +1,165 @@
+/**
+ * Async write queue for non-critical memory writes.
+ *
+ * Pattern: 2026-frontier agent memory layers (Mem0, Zep) defer audit and
+ * observability writes off the request thread to keep p95 retrieval latency
+ * low. Mem0 reports ~91% p95 latency reduction with this pattern; voice
+ * agents in particular need it since there's no scrollback to recover.
+ *
+ * Scope: only non-user-visible writes (transcripts, recall traces, outcomes,
+ * access log). User-driven mutations (memory_write, user_model, pinChunk,
+ * updateFile) stay synchronous so the user sees immediate persistence.
+ *
+ * Trade-offs:
+ *  - `recordOutcome` updates `last_outcome_score` which feeds retrieval
+ *    ranking. Async-deferring it means up to one flush interval (~250ms) of
+ *    EMA staleness — acceptable for ranking signal that already smooths.
+ *  - On hard process kill (SIGKILL, OOM) the in-flight queue is lost. Audit
+ *    writes are best-effort by design; existing call sites already swallow
+ *    errors. Drain on SIGTERM/SIGUSR1 covers planned shutdowns.
+ */
+import pino from 'pino';
+const logger = pino({ name: 'clementine.write-queue' });
+/**
+ * Minimal write-behind queue for the memory store. Not concurrent-safe at
+ * the JS level — assumes the single-process daemon model that Clementine
+ * already uses for all memory writes.
+ */
+export class WriteQueue {
+    store;
+    buffer = [];
+    timer = null;
+    flushIntervalMs;
+    flushSize;
+    maxBuffer;
+    flushing = false;
+    dropped = 0;
+    constructor(store, opts = {}) {
+        this.store = store;
+        this.flushIntervalMs = opts.flushIntervalMs ?? 250;
+        this.flushSize = opts.flushSize ?? 50;
+        this.maxBuffer = opts.maxBuffer ?? 5000;
+    }
+    /** Begin periodic flushing. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush();
+        }, this.flushIntervalMs);
+        // Don't keep the event loop alive just for the queue.
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    /** Stop the periodic timer (does not drain). */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    enqueue(op) {
+        if (this.buffer.length >= this.maxBuffer) {
+            // Hard cap — drop oldest to bound memory. Surfaces in stats().
+            this.buffer.shift();
+            this.dropped++;
+        }
+        this.buffer.push(op);
+        if (this.buffer.length >= this.flushSize) {
+            void this.flush();
+        }
+    }
+    size() {
+        return this.buffer.length;
+    }
+    stats() {
+        return { size: this.buffer.length, dropped: this.dropped };
+    }
+    /**
+     * Apply all queued ops to the store. Ops that fail are logged and skipped;
+     * they don't block the rest of the batch. Concurrent calls collapse — the
+     * second caller exits immediately if a flush is in progress.
+     */
+    async flush() {
+        if (this.flushing)
+            return { flushed: 0, errors: 0 };
+        if (this.buffer.length === 0)
+            return { flushed: 0, errors: 0 };
+        this.flushing = true;
+        const batch = this.buffer.splice(0);
+        let flushed = 0;
+        let errors = 0;
+        try {
+            for (const op of batch) {
+                try {
+                    this.apply(op);
+                    flushed++;
+                }
+                catch (err) {
+                    errors++;
+                    logger.warn({ err, kind: op.kind }, 'Write op failed');
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+        return { flushed, errors };
+    }
+    /**
+     * Stop the timer and flush everything currently buffered. Loops until
+     * the buffer is empty so any ops enqueued during a flush also drain.
+     */
+    async drain() {
+        this.stop();
+        // Yield to let any in-flight flush finish, then keep flushing until empty.
+        while (this.buffer.length > 0 || this.flushing) {
+            if (this.flushing) {
+                await new Promise((r) => setTimeout(r, 5));
+                continue;
+            }
+            await this.flush();
+        }
+    }
+    apply(op) {
+        // Call the sync variants directly. The public methods route through this
+        // queue when enabled — calling them here would re-enqueue and infinite-loop.
+        switch (op.kind) {
+            case 'transcript-turn':
+                this.store._saveTurnSync?.(op.sessionKey, op.role, op.content, op.model);
+                break;
+            case 'recall':
+                this.store._logRecallTraceSync?.({
+                    sessionKey: op.sessionKey,
+                    messageId: op.messageId,
+                    query: op.query,
+                    chunkIds: op.chunkIds,
+                    scores: op.scores,
+                    agentSlug: op.agentSlug,
+                });
+                break;
+            case 'outcome':
+                this.store._recordOutcomeSync?.(op.outcomes, op.sessionKey);
+                break;
+            case 'access':
+                this.store._recordAccessSync?.(op.chunkIds, op.accessType);
+                break;
+        }
+    }
+}
+/** Convenience: install SIGTERM/SIGUSR1 drain hooks on the process. */
+export function installShutdownDrain(queue) {
+    const drainAndExit = (signal) => {
+        logger.info({ signal, pending: queue.size() }, 'Draining write queue on shutdown');
+        queue
+            .drain()
+            .catch((err) => logger.warn({ err }, 'Drain failed'))
+            .finally(() => {
+            // Don't exit here — caller's signal handler may have other cleanup.
+            // We just guarantee the queue is empty before the process tears down.
+        });
+    };
+    process.on('SIGTERM', () => drainAndExit('SIGTERM'));
+    process.on('SIGUSR1', () => drainAndExit('SIGUSR1'));
+}
+//# sourceMappingURL=write-queue.js.map

package/dist/tools/memory-tools.js

@@ -362,11 +362,48 @@ export function registerMemoryTools(server) {
         }
         return textResult(`Unknown action: ${action}`);
     });
+    // ── 2b. memory_record_procedure ────────────────────────────────────────
+    server.tool('memory_record_procedure', getToolDescription('memory_record_procedure') ?? 'Record a learned workflow as a durable procedure. Use when you notice a repeating multi-step task ("how Nate ships a release", "how to handle inbound replies"). Stored under 00-System/procedures/ with category=procedure and trigger verbs that surface it later. Different from memory_write/MEMORY.md: those store facts, this stores reusable HOW-TO. From Mem0\'s 2026 procedural-memory pattern.', {
+        title: z.string().describe('Short procedure title (becomes filename slug)'),
+        steps: z.string().describe('Numbered steps or markdown body describing how to perform the task'),
+        triggers: z.array(z.string()).min(1).describe('Verb phrases (e.g. ["ship release", "publish to npm"]) that should surface this procedure when the user query contains them. Lowercase preferred.'),
+        notes: z.string().optional().describe('Optional context: when to use, when NOT to use, gotchas'),
+    }, async ({ title, steps, triggers, notes }) => {
+        const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+        if (!slug)
+            return textResult('Error: title must contain alphanumerics');
+        const proceduresDir = path.join(SYSTEM_DIR, 'procedures');
+        mkdirSync(proceduresDir, { recursive: true });
+        const filePath = path.join(proceduresDir, `${slug}.md`);
+        const triggersYaml = triggers.map((t) => `  - ${JSON.stringify(t.toLowerCase())}`).join('\n');
+        const body = [
+            '---',
+            `title: ${JSON.stringify(title)}`,
+            'category: procedure',
+            'triggers:',
+            triggersYaml,
+            `created_at: ${new Date().toISOString()}`,
+            ACTIVE_AGENT_SLUG ? `agent_slug: ${JSON.stringify(ACTIVE_AGENT_SLUG)}` : '',
+            '---',
+            '',
+            `# ${title}`,
+            '',
+            '## Steps',
+            '',
+            steps.trim(),
+            '',
+            ...(notes ? ['## Notes', '', notes.trim(), ''] : []),
+        ].filter((line) => line !== '').join('\n') + '\n';
+        writeFileSync(filePath, body, 'utf-8');
+        const rel = path.relative(VAULT_DIR, filePath);
+        await incrementalSync(rel, ACTIVE_AGENT_SLUG ?? undefined);
+        return textResult(`Recorded procedure: ${rel} (triggers: ${triggers.join(', ')})`);
+    });
     // ── 3. memory_search ───────────────────────────────────────────────────
     server.tool('memory_search', getToolDescription('memory_search') ?? 'FTS5 search across all vault notes. Returns matching chunks with relevance scores. Optional category/topic filters narrow results.', {
         query: z.string().describe('Search text'),
         limit: z.number().optional().describe('Max results (default 20)'),
-        category: z.enum(['facts', 'events', 'discoveries', 'preferences', 'advice']).optional().describe('Filter by category'),
+        category: z.enum(['facts', 'events', 'discoveries', 'preferences', 'advice', 'procedure']).optional().describe('Filter by category'),
         topic: z.string().optional().describe('Filter by topic'),
     }, async ({ query, limit, category, topic }) => {
         const maxResults = limit ?? 20;

package/dist/types.d.ts

@@ -7,7 +7,7 @@ export interface SearchResult {
     content: string;
     score: float;
     chunkType: string;
-    matchType: 'fts' | 'recency' | 'timeline' | 'vector';
+    matchType: 'fts' | 'recency' | 'timeline' | 'vector' | 'graph';
     lastUpdated: string;
     chunkId: number;
     salience: number;
@@ -17,7 +17,7 @@ export interface SearchResult {
     topic?: string | null;
     pinned?: boolean;
 }
-export type ChunkCategory = 'facts' | 'events' | 'discoveries' | 'preferences' | 'advice';
+export type ChunkCategory = 'facts' | 'events' | 'discoveries' | 'preferences' | 'advice' | 'procedure';
 export interface Chunk {
     sourceFile: string;
     section: string;
@@ -716,6 +716,14 @@ export interface RemoteAccessConfig {
     autoPost: boolean;
     lastStarted?: string;
 }
+export interface SessionRecord {
+    id: string;
+    expiresAt: number;
+    persistent: boolean;
+    createdAt: number;
+    lastUsedAt: number;
+    userAgent?: string;
+}
 export interface ConfigRevision {
     id?: number;
     agentSlug: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",