myagentmemory 0.4.3

package/dist/cli.js

@@ -0,0 +1,510 @@
+#!/usr/bin/env node
+/**
+ * agent-memory CLI
+ *
+ * Subcommands:
+ *   context    — Build & print context injection string to stdout
+ *   write      — Write to memory files
+ *   read       — Read memory files
+ *   scratchpad — Manage checklist
+ *   search     — Search via qmd
+ *   init       — Create dirs, detect qmd, setup collection
+ *   status     — Show config, qmd status, file counts
+ *
+ * Global flags:
+ *   --dir <path>   Override memory directory
+ *   --json         Machine-readable JSON output
+ */
+import * as fs from "node:fs";
+import { _setBaseDir, buildMemoryContext, checkCollection, dailyPath, detectQmd, ensureDirs, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdResultPath, getQmdResultText, getScratchpadFile, nowTimestamp, parseScratchpad, readFileSafe, runQmdSearch, scheduleQmdUpdate, searchRelevantMemories, serializeScratchpad, setupQmdCollection, todayStr, } from "./core.js";
+function parseArgs(argv) {
+    const flags = {};
+    const positional = [];
+    let command = "";
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!command && !arg.startsWith("-")) {
+            command = arg;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith("--")) {
+                flags[key] = next;
+                i++;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else if (!arg.startsWith("-")) {
+            positional.push(arg);
+        }
+    }
+    return { command, flags, positional };
+}
+function getFlag(flags, key) {
+    const val = flags[key];
+    return typeof val === "string" ? val : undefined;
+}
+function hasFlag(flags, key) {
+    return key in flags;
+}
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+function output(data, json) {
+    if (json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else if (typeof data === "string") {
+        console.log(data);
+    }
+    else {
+        console.log(JSON.stringify(data, null, 2));
+    }
+}
+function exitError(message, json) {
+    if (json) {
+        console.error(JSON.stringify({ error: message }));
+    }
+    else {
+        console.error(`Error: ${message}`);
+    }
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+async function cmdContext(flags) {
+    const json = hasFlag(flags, "json");
+    const noSearch = hasFlag(flags, "no-search");
+    ensureDirs();
+    const searchResults = noSearch ? "" : await searchRelevantMemories("");
+    const context = buildMemoryContext(searchResults);
+    if (json) {
+        output({ context, directory: getMemoryDir() }, true);
+    }
+    else {
+        if (context) {
+            process.stdout.write(context);
+        }
+    }
+}
+async function cmdWrite(flags) {
+    const json = hasFlag(flags, "json");
+    const target = getFlag(flags, "target");
+    const content = getFlag(flags, "content");
+    const mode = getFlag(flags, "mode") ?? "append";
+    if (!target || !["long_term", "daily"].includes(target)) {
+        exitError("--target must be 'long_term' or 'daily'", json);
+    }
+    if (!content) {
+        exitError("--content is required", json);
+    }
+    ensureDirs();
+    const ts = nowTimestamp();
+    const sid = "cli";
+    if (target === "daily") {
+        const filePath = dailyPath(todayStr());
+        const existing = readFileSafe(filePath) ?? "";
+        const separator = existing.trim() ? "\n\n" : "";
+        const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
+        fs.writeFileSync(filePath, existing + separator + stamped, "utf-8");
+        await ensureQmdAvailableForUpdate();
+        scheduleQmdUpdate();
+        output(json
+            ? { ok: true, path: filePath, target, mode: "append", timestamp: ts }
+            : `Appended to daily log: ${filePath}`, json);
+        return;
+    }
+    // long_term
+    const memFile = getMemoryFile();
+    const existing = readFileSafe(memFile) ?? "";
+    if (mode === "overwrite") {
+        const stamped = `<!-- last updated: ${ts} [${sid}] -->\n${content}`;
+        fs.writeFileSync(memFile, stamped, "utf-8");
+    }
+    else {
+        const separator = existing.trim() ? "\n\n" : "";
+        const stamped = `<!-- ${ts} [${sid}] -->\n${content}`;
+        fs.writeFileSync(memFile, existing + separator + stamped, "utf-8");
+    }
+    await ensureQmdAvailableForUpdate();
+    scheduleQmdUpdate();
+    output(json
+        ? { ok: true, path: memFile, target, mode, timestamp: ts }
+        : `${mode === "overwrite" ? "Overwrote" : "Appended to"} MEMORY.md`, json);
+}
+async function cmdRead(flags) {
+    const json = hasFlag(flags, "json");
+    const target = getFlag(flags, "target");
+    const date = getFlag(flags, "date");
+    if (!target || !["long_term", "scratchpad", "daily", "list"].includes(target)) {
+        exitError("--target must be 'long_term', 'scratchpad', 'daily', or 'list'", json);
+    }
+    ensureDirs();
+    if (target === "list") {
+        try {
+            const files = fs
+                .readdirSync(getDailyDir())
+                .filter((f) => f.endsWith(".md"))
+                .sort()
+                .reverse();
+            if (json) {
+                output({ files }, true);
+            }
+            else if (files.length === 0) {
+                console.log("No daily logs found.");
+            }
+            else {
+                console.log(`Daily logs:\n${files.map((f) => `- ${f}`).join("\n")}`);
+            }
+        }
+        catch {
+            output(json ? { files: [] } : "No daily logs directory.", json);
+        }
+        return;
+    }
+    if (target === "daily") {
+        const d = date ?? todayStr();
+        const filePath = dailyPath(d);
+        const content = readFileSafe(filePath);
+        if (!content) {
+            output(json ? { content: null, date: d } : `No daily log for ${d}.`, json);
+            return;
+        }
+        output(json ? { content, date: d, path: filePath } : content, json);
+        return;
+    }
+    if (target === "scratchpad") {
+        const content = readFileSafe(getScratchpadFile());
+        if (!content?.trim()) {
+            output(json ? { content: null } : "SCRATCHPAD.md is empty or does not exist.", json);
+            return;
+        }
+        output(json ? { content, path: getScratchpadFile() } : content, json);
+        return;
+    }
+    // long_term
+    const content = readFileSafe(getMemoryFile());
+    if (!content) {
+        output(json ? { content: null } : "MEMORY.md is empty or does not exist.", json);
+        return;
+    }
+    output(json ? { content, path: getMemoryFile() } : content, json);
+}
+async function cmdScratchpad(flags, positional) {
+    const json = hasFlag(flags, "json");
+    const action = positional[0];
+    const text = getFlag(flags, "text");
+    if (!action || !["add", "done", "undo", "clear_done", "list"].includes(action)) {
+        exitError("Usage: agent-memory scratchpad <add|done|undo|clear_done|list> [--text <text>]", json);
+    }
+    ensureDirs();
+    const spFile = getScratchpadFile();
+    const existing = readFileSafe(spFile) ?? "";
+    let items = parseScratchpad(existing);
+    if (action === "list") {
+        if (items.length === 0) {
+            output(json ? { items: [], count: 0, open: 0 } : "Scratchpad is empty.", json);
+            return;
+        }
+        if (json) {
+            output({
+                items: items.map((i) => ({ done: i.done, text: i.text })),
+                count: items.length,
+                open: items.filter((i) => !i.done).length,
+            }, true);
+        }
+        else {
+            console.log(serializeScratchpad(items));
+        }
+        return;
+    }
+    if (action === "add") {
+        if (!text)
+            exitError("--text is required for add", json);
+        const ts = nowTimestamp();
+        items.push({ done: false, text: text, meta: `<!-- ${ts} [cli] -->` });
+        fs.writeFileSync(spFile, serializeScratchpad(items), "utf-8");
+        await ensureQmdAvailableForUpdate();
+        scheduleQmdUpdate();
+        output(json ? { ok: true, action, text } : `Added: - [ ] ${text}`, json);
+        return;
+    }
+    if (action === "done" || action === "undo") {
+        if (!text)
+            exitError(`--text is required for ${action}`, json);
+        const needle = text.toLowerCase();
+        const targetDone = action === "done";
+        let matched = false;
+        for (const item of items) {
+            if (item.done !== targetDone && item.text.toLowerCase().includes(needle)) {
+                item.done = targetDone;
+                matched = true;
+                break;
+            }
+        }
+        if (!matched) {
+            exitError(`No matching ${targetDone ? "open" : "done"} item found for: "${text}"`, json);
+        }
+        fs.writeFileSync(spFile, serializeScratchpad(items), "utf-8");
+        await ensureQmdAvailableForUpdate();
+        scheduleQmdUpdate();
+        output(json ? { ok: true, action, text } : "Updated.", json);
+        return;
+    }
+    if (action === "clear_done") {
+        const before = items.length;
+        items = items.filter((i) => !i.done);
+        const removed = before - items.length;
+        fs.writeFileSync(spFile, serializeScratchpad(items), "utf-8");
+        await ensureQmdAvailableForUpdate();
+        scheduleQmdUpdate();
+        output(json ? { ok: true, action, removed } : `Cleared ${removed} done item(s).`, json);
+    }
+}
+async function cmdSearch(flags) {
+    const json = hasFlag(flags, "json");
+    const query = getFlag(flags, "query");
+    const mode = (getFlag(flags, "mode") ?? "keyword");
+    const limit = Number.parseInt(getFlag(flags, "limit") ?? "5", 10);
+    if (!query)
+        exitError("--query is required", json);
+    if (!["keyword", "semantic", "deep"].includes(mode)) {
+        exitError("--mode must be 'keyword', 'semantic', or 'deep'", json);
+    }
+    const qmdFound = await detectQmd();
+    if (!qmdFound) {
+        exitError("qmd is not installed. Install: bun install -g https://github.com/tobi/qmd", json);
+    }
+    const collName = getCollectionName();
+    const hasCollection = await checkCollection(collName);
+    if (!hasCollection) {
+        exitError(`qmd collection '${collName}' not found. Run: agent-memory init`, json);
+    }
+    try {
+        const { results, stderr } = await runQmdSearch(mode, query, limit);
+        if (json) {
+            output({ mode, query, count: results.length, results }, true);
+            return;
+        }
+        if (results.length === 0) {
+            const needsEmbed = /need embeddings/i.test(stderr ?? "");
+            if (needsEmbed && (mode === "semantic" || mode === "deep")) {
+                console.log(`No results found. qmd reports missing embeddings — run: qmd embed`);
+            }
+            else {
+                console.log(`No results found for "${query}" (mode: ${mode}).`);
+            }
+            return;
+        }
+        for (let i = 0; i < results.length; i++) {
+            const r = results[i];
+            const filePath = getQmdResultPath(r);
+            const text = getQmdResultText(r);
+            console.log(`--- Result ${i + 1} ---`);
+            if (filePath)
+                console.log(`File: ${filePath}`);
+            if (r.score != null)
+                console.log(`Score: ${r.score}`);
+            if (text)
+                console.log(text);
+            console.log("");
+        }
+    }
+    catch (err) {
+        exitError(`Search failed: ${err instanceof Error ? err.message : String(err)}`, json);
+    }
+}
+async function cmdInit(flags) {
+    const json = hasFlag(flags, "json");
+    ensureDirs();
+    const dir = getMemoryDir();
+    const qmdFound = await detectQmd();
+    let collectionCreated = false;
+    if (qmdFound) {
+        const collName = getCollectionName();
+        const hasCollection = await checkCollection(collName);
+        if (!hasCollection) {
+            collectionCreated = await setupQmdCollection();
+        }
+    }
+    if (json) {
+        output({
+            ok: true,
+            directory: dir,
+            qmd: qmdFound,
+            collectionCreated,
+        }, true);
+    }
+    else {
+        console.log(`Memory directory: ${dir}`);
+        console.log(`  MEMORY.md, SCRATCHPAD.md, daily/ created.`);
+        if (qmdFound) {
+            if (collectionCreated) {
+                console.log(`  qmd collection '${getCollectionName()}' created.`);
+            }
+            else {
+                console.log(`  qmd collection '${getCollectionName()}' already exists.`);
+            }
+        }
+        else {
+            console.log(`  qmd not found — search features unavailable.`);
+            console.log(`  Install: bun install -g https://github.com/tobi/qmd`);
+        }
+    }
+}
+async function cmdStatus(flags) {
+    const json = hasFlag(flags, "json");
+    ensureDirs();
+    const dir = getMemoryDir();
+    const memFile = getMemoryFile();
+    const spFile = getScratchpadFile();
+    const dailyDir = getDailyDir();
+    const memContent = readFileSafe(memFile);
+    const spContent = readFileSafe(spFile);
+    let dailyCount = 0;
+    try {
+        dailyCount = fs.readdirSync(dailyDir).filter((f) => f.endsWith(".md")).length;
+    }
+    catch {
+        // directory may not exist
+    }
+    const qmdFound = await detectQmd();
+    let hasCollection = false;
+    if (qmdFound) {
+        hasCollection = await checkCollection();
+    }
+    if (json) {
+        output({
+            directory: dir,
+            memoryFile: {
+                exists: memContent !== null,
+                chars: memContent?.length ?? 0,
+                lines: memContent ? memContent.split("\n").length : 0,
+            },
+            scratchpadFile: {
+                exists: spContent !== null,
+                items: spContent ? parseScratchpad(spContent).length : 0,
+                openItems: spContent ? parseScratchpad(spContent).filter((i) => !i.done).length : 0,
+            },
+            dailyLogs: dailyCount,
+            qmd: {
+                available: qmdFound,
+                collection: hasCollection ? getCollectionName() : null,
+            },
+        }, true);
+    }
+    else {
+        console.log(`Memory directory: ${dir}`);
+        console.log("");
+        if (memContent !== null) {
+            const lines = memContent.split("\n").length;
+            console.log(`MEMORY.md: ${memContent.length} chars, ${lines} lines`);
+        }
+        else {
+            console.log("MEMORY.md: not created yet");
+        }
+        if (spContent !== null) {
+            const items = parseScratchpad(spContent);
+            const open = items.filter((i) => !i.done).length;
+            console.log(`SCRATCHPAD.md: ${items.length} items (${open} open)`);
+        }
+        else {
+            console.log("SCRATCHPAD.md: not created yet");
+        }
+        console.log(`Daily logs: ${dailyCount} file(s)`);
+        console.log("");
+        if (qmdFound) {
+            console.log(`qmd: available`);
+            console.log(`Collection '${getCollectionName()}': ${hasCollection ? "configured" : "not configured — run: agent-memory init"}`);
+        }
+        else {
+            console.log("qmd: not installed");
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Usage
+// ---------------------------------------------------------------------------
+function printUsage() {
+    console.log(`agent-memory — persistent memory for coding agents
+
+Usage:
+  agent-memory <command> [options]
+
+Commands:
+  context     Build & print context injection string
+  write       Write to memory files
+  read        Read memory files
+  scratchpad  Manage checklist items
+  search      Search across memory files (requires qmd)
+  init        Initialize memory directory and qmd collection
+  status      Show configuration and status
+
+Global flags:
+  --dir <path>   Override memory directory
+  --json         Machine-readable JSON output
+
+Examples:
+  agent-memory init
+  agent-memory write --target long_term --content "User prefers dark mode"
+  agent-memory write --target daily --content "Fixed auth bug in login flow"
+  agent-memory read --target long_term
+  agent-memory read --target daily --date 2026-02-15
+  agent-memory read --target list
+  agent-memory scratchpad add --text "Review PR #42"
+  agent-memory scratchpad list
+  agent-memory scratchpad done --text "PR #42"
+  agent-memory search --query "database choice" --mode keyword
+  agent-memory context --no-search
+  agent-memory status --json`);
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    const { command, flags, positional } = parseArgs(process.argv.slice(2));
+    const json = hasFlag(flags, "json");
+    // Apply --dir override
+    const dir = getFlag(flags, "dir");
+    if (dir) {
+        _setBaseDir(dir);
+    }
+    if (!command || command === "help" || hasFlag(flags, "help")) {
+        printUsage();
+        return;
+    }
+    switch (command) {
+        case "context":
+            await cmdContext(flags);
+            break;
+        case "write":
+            await cmdWrite(flags);
+            break;
+        case "read":
+            await cmdRead(flags);
+            break;
+        case "scratchpad":
+            await cmdScratchpad(flags, positional);
+            break;
+        case "search":
+            await cmdSearch(flags);
+            break;
+        case "init":
+            await cmdInit(flags);
+            break;
+        case "status":
+            await cmdStatus(flags);
+            break;
+        default:
+            exitError(`Unknown command: ${command}. Run 'agent-memory help' for usage.`, json);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/core.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Shared core logic for agent-memory.
+ *
+ * Core logic for agent-memory CLI and skills.
+ * Zero pi peer dependencies — only node:fs, node:path, node:child_process.
+ */
+import { execFile } from "node:child_process";
+/** Override base directory (for testing or platform-specific defaults). */
+export declare function _setBaseDir(baseDir: string): void;
+/** Reset to default paths. */
+export declare function _resetBaseDir(): void;
+/** Get the current memory directory path. */
+export declare function getMemoryDir(): string;
+/** Get the current MEMORY.md path. */
+export declare function getMemoryFile(): string;
+/** Get the current SCRATCHPAD.md path. */
+export declare function getScratchpadFile(): string;
+/** Get the current daily log directory path. */
+export declare function getDailyDir(): string;
+export declare function ensureDirs(): void;
+export declare function todayStr(): string;
+export declare function yesterdayStr(): string;
+export declare function nowTimestamp(): string;
+export declare function shortSessionId(sessionId: string): string;
+export declare function readFileSafe(filePath: string): string | null;
+export declare function dailyPath(date: string): string;
+export declare const RESPONSE_PREVIEW_MAX_CHARS = 4000;
+export declare const RESPONSE_PREVIEW_MAX_LINES = 120;
+export type TruncateMode = "start" | "end" | "middle";
+export interface PreviewResult {
+    preview: string;
+    truncated: boolean;
+    totalLines: number;
+    totalChars: number;
+    previewLines: number;
+    previewChars: number;
+}
+export declare function truncateLines(lines: string[], maxLines: number, mode: TruncateMode): {
+    lines: string[];
+    truncated: boolean;
+};
+export declare function truncateText(text: string, maxChars: number, mode: TruncateMode): {
+    text: string;
+    truncated: boolean;
+};
+export declare function buildPreview(content: string, options: {
+    maxLines: number;
+    maxChars: number;
+    mode: TruncateMode;
+}): PreviewResult;
+export declare function formatPreviewBlock(label: string, content: string, mode: TruncateMode): string;
+export declare function formatContextSection(label: string, content: string, mode: TruncateMode, maxLines: number, maxChars: number): string;
+export interface ScratchpadItem {
+    done: boolean;
+    text: string;
+    meta: string;
+}
+export declare function parseScratchpad(content: string): ScratchpadItem[];
+export declare function serializeScratchpad(items: ScratchpadItem[]): string;
+export declare function buildMemoryContext(searchResults?: string): string;
+type ExecFileFn = typeof execFile;
+/** Override execFile implementation (for testing). */
+export declare function _setExecFileForTest(fn: ExecFileFn): void;
+/** Reset execFile implementation (for testing). */
+export declare function _resetExecFileForTest(): void;
+/** Set qmd availability flag (for testing). */
+export declare function _setQmdAvailable(value: boolean): void;
+/** Get current qmd availability flag. */
+export declare function _getQmdAvailable(): boolean;
+/** Get current update timer (for testing). */
+export declare function _getUpdateTimer(): ReturnType<typeof setTimeout> | null;
+/** Clear the update timer (for testing). */
+export declare function _clearUpdateTimer(): void;
+/** Get the current QMD collection name. */
+export declare function getCollectionName(): string;
+/** Set the QMD collection name (for platform-specific overrides). */
+export declare function setCollectionName(name: string): void;
+export declare function qmdInstallInstructions(): string;
+export declare function qmdCollectionInstructions(): string;
+/** Auto-create the qmd collection and path contexts. */
+export declare function setupQmdCollection(): Promise<boolean>;
+export declare function detectQmd(): Promise<boolean>;
+export declare function checkCollection(name?: string): Promise<boolean>;
+export declare function getQmdUpdateMode(): "background" | "manual" | "off";
+export declare function ensureQmdAvailableForUpdate(): Promise<boolean>;
+export declare function scheduleQmdUpdate(): void;
+export declare function runQmdUpdateNow(): Promise<void>;
+/** Search for memories relevant to the user's prompt. Returns formatted markdown or empty string on error. */
+export declare function searchRelevantMemories(prompt: string): Promise<string>;
+export interface QmdSearchResult {
+    path?: string;
+    file?: string;
+    score?: number;
+    content?: string;
+    chunk?: string;
+    snippet?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+export declare function getQmdResultPath(r: QmdSearchResult): string | undefined;
+export declare function getQmdResultText(r: QmdSearchResult): string;
+export declare function runQmdSearch(mode: "keyword" | "semantic" | "deep", query: string, limit: number): Promise<{
+    results: QmdSearchResult[];
+    stderr: string;
+}>;
+export interface ToolResult {
+    text: string;
+    details: Record<string, unknown>;
+    isError?: boolean;
+}
+export declare function memoryWrite(params: {
+    target: "long_term" | "daily";
+    content: string;
+    mode?: "append" | "overwrite";
+    sessionId?: string;
+}): Promise<ToolResult>;
+export declare function scratchpadAction(params: {
+    action: "add" | "done" | "undo" | "clear_done" | "list";
+    text?: string;
+    sessionId?: string;
+}): Promise<ToolResult>;
+export declare function memoryRead(params: {
+    target: "long_term" | "scratchpad" | "daily" | "list";
+    date?: string;
+}): Promise<ToolResult>;
+export declare function memorySearch(params: {
+    query: string;
+    mode?: "keyword" | "semantic" | "deep";
+    limit?: number;
+}): Promise<ToolResult>;
+export {};