@fonlan/dsh-gitmemo 0.1.0

package/lib/index.js

@@ -0,0 +1,329 @@
+/**
+ * dsh-gitmemo — Git-backed long-term memory for DeepSeek Harness.
+ *
+ * A Cordis plugin mirroring gitmemo (https://github.com/fonlan/gitmemo):
+ * the agent stores completed task outcomes as markdown entries in a local
+ * `.mem` git repository and searches them before starting new work.
+ *
+ * This plugin registers on the host plane:
+ *  - five model-facing tools: `mem_init`, `mem_search`, `mem_read`,
+ *    `mem_write`, `mem_delete` (backed by {@link GitMemo});
+ *  - an always-on system-prompt section with the full memory workflow rules;
+ *  - a per-session seed of the most recent memory titles.
+ *
+ * @module dsh-gitmemo
+ */
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { GitMemo } from "./mem.js";
+/** Cordis plugin name. */
+const name = "dsh-gitmemo";
+/** Host services this plugin needs. */
+const inject = ["tools", "systemPrompt"];
+/** Plugin configuration (all optional). */
+const Config = z.object({
+    /** Name of the memory repo directory at the project root. Default ".mem". */
+    memDirName: z.string().default(".mem"),
+    /** Max search hits per mem_search call. Default 20. */
+    searchLimit: z.number().default(20),
+    /** Align the .mem branch with the project branch on writes. Default true. */
+    branchAlign: z.boolean().default(true),
+    /** Number of most recent memory titles injected into each new session's system prompt (0 disables). Default 5. */
+    recentContextLimit: z.number().default(5),
+    /** Optional explicit project root; defaults to the calling session's cwd. */
+    projectRoot: z.string()
+});
+/** The calling agent's session workspace, when it has one. */
+function sessionCwd(exec) {
+    return exec.agent?.session?.header?.cwd;
+}
+/** Build the engine for one tool call. */
+function engineFor(exec, config) {
+    const cwd = sessionCwd(exec) ?? process.cwd();
+    const root = config.projectRoot ?? cwd;
+    const engineConfig = {
+        memDirName: config.memDirName,
+        searchLimit: config.searchLimit,
+        branchAlign: config.branchAlign
+    };
+    return new GitMemo(root, engineConfig);
+}
+const SEARCH_HIT = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        hash: { type: "string", required: true, description: "Full commit hash of the memory entry." },
+        title: { type: "string", required: true, description: "Commit subject (the entry title)." },
+        date: { type: "string", required: true, description: "Commit date in ISO format." }
+    }
+};
+/** Render one tool output block as plain text. */
+function textBlock(text) {
+    return [{ type: "text", text }];
+}
+/** Register every model-facing tool. */
+function registerMemTools(ctx, config) {
+    void config;
+    ctx.tools.register(defineTool({
+        name: "mem_init",
+        description: "Initialize the gitmemo long-term memory repository (.mem git repo) at the project root. All other mem_* tools auto-initialize, so this is only needed to check or force initialization.",
+        parameters: {},
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    path: { type: "string", required: true, description: "Absolute path of the memory repository." }
+                }
+            },
+            render: (_args, value) => textBlock("OK: Memory repo ready at " + value.path)
+        },
+        isConcurrencySafe: () => false,
+        async execute(_args, exec) {
+            const memo = engineFor(exec, config);
+            const path = await memo.init();
+            return { path };
+        },
+        presentCall: () => ({ card: "generic", title: "Init gitmemo memory", kind: "other" })
+    }));
+    ctx.tools.register(defineTool({
+        name: "mem_search",
+        description: "Search the gitmemo long-term memory (.mem git repo) for past task outcomes. Call BEFORE starting work: extract 3-5 keywords from the user request, search, and reuse prior conclusions when relevant. Returns up to 20 hits formatted as `hash|title|date`; when nothing relevant appears, paginate with `skip` 20, 40, ...",
+        parameters: {
+            keywords: {
+                type: "string",
+                required: true,
+                description: "Comma-separated keywords (3-5 recommended), e.g. \"auth,rate-limit,login\"."
+            },
+            skip: {
+                type: "integer",
+                description: "Pagination offset (default 0)."
+            },
+            mode: {
+                type: "string",
+                enum: ["and", "or", "auto"],
+                description: "and=strict (all keywords), or=broad (any keyword), auto=AND first then OR fallback (default auto)."
+            }
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    mode: { type: "string", required: true, description: "The mode actually used (and or or)." },
+                    results: { type: "array", required: true, items: SEARCH_HIT }
+                }
+            },
+            render: (_args, value) => {
+                const lines = value.results.map((hit) => hit.hash + "|" + hit.title + "|" + hit.date);
+                return textBlock(lines.length > 0 ? lines.join("\n") : "(no matching memories)");
+            }
+        },
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const memo = engineFor(exec, config);
+            return await memo.search(args.keywords, args.skip ?? 0, args.mode ?? "auto");
+        },
+        presentCall: (args) => ({
+            card: "generic",
+            title: "Search memory: " + args.keywords,
+            kind: "other"
+        })
+    }));
+    ctx.tools.register(defineTool({
+        name: "mem_read",
+        description: "Read one gitmemo memory entry by commit hash (returned by mem_search). Select only the most relevant memories before reading — at most 5 when a search returns more.",
+        parameters: {
+            commit_hash: {
+                type: "string",
+                required: true,
+                description: "Commit hash of the memory entry to read."
+            }
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    commit_hash: { type: "string", required: true },
+                    file: { type: "string", required: true, description: "Entry file path inside the memory repo." },
+                    content: { type: "string", required: true, description: "Full markdown of the memory entry." }
+                }
+            },
+            render: (_args, value) => textBlock(value.content)
+        },
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const memo = engineFor(exec, config);
+            const { file, content } = await memo.read(args.commit_hash);
+            return { commit_hash: args.commit_hash, file, content };
+        },
+        presentCall: (args) => ({
+            card: "generic",
+            title: "Read memory " + args.commit_hash.slice(0, 8),
+            kind: "read"
+        })
+    }));
+    ctx.tools.register(defineTool({
+        name: "mem_write",
+        description: "Store a completed task outcome in the gitmemo long-term memory (.mem git repo). Write ONLY when the task is complete AND repo-related AND the outcome is valuable/reusable OR the user explicitly asked to remember. Entry markdown goes through `content` (or `content_file`); `title` is a short \"[module] action + object\"; `body` is an optional 1-3 sentence commit body (never memory content). The entry is committed as `.mem/entries/<timestamp>-<slug>.md` and the .mem branch follows the project branch.",
+        parameters: {
+            title: {
+                type: "string",
+                required: true,
+                description: "Short \"[module] action + object\" title, e.g. \"[auth] add rate-limit for login\"."
+            },
+            content: {
+                type: "string",
+                description: "The memory entry markdown (YAML front matter + sections). Provide exactly one of content / content_file / file."
+            },
+            content_file: {
+                type: "string",
+                description: "Path to a file holding the entry markdown (alternative to content; temp files are deleted after a successful write)."
+            },
+            file: {
+                type: "string",
+                description: "An existing .mem/entries/... path to commit in place (alternative to content / content_file)."
+            },
+            body: {
+                type: "string",
+                description: "Optional commit body: 1-3 sentence summary + metadata. Not memory content."
+            },
+            body_file: {
+                type: "string",
+                description: "Path to a file holding the commit body (alternative to body)."
+            }
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    hash: { type: "string", required: true, description: "Commit hash of the new memory entry." },
+                    file: { type: "string", required: true, description: "Entry file path inside the memory repo." }
+                }
+            },
+            render: (_args, value) => textBlock("OK: " + value.hash + "|" + value.file)
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const memo = engineFor(exec, config);
+            return await memo.write({
+                title: args.title,
+                content: args.content,
+                contentFile: args.content_file,
+                file: args.file,
+                body: args.body,
+                bodyFile: args.body_file
+            });
+        },
+        presentCall: (args) => ({
+            card: "generic",
+            title: "Write memory: " + args.title,
+            kind: "other"
+        })
+    }));
+    ctx.tools.register(defineTool({
+        name: "mem_delete",
+        description: "Delete a gitmemo memory entry by commit hash. Use when the user is unsatisfied with a stored outcome: delete, redo the task from feedback, then mem_write a corrected entry.",
+        parameters: {
+            commit_hash: {
+                type: "string",
+                required: true,
+                description: "Commit hash of the memory entry to delete."
+            }
+        },
+        output: {
+            schema: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    file: { type: "string", required: true, description: "Deleted entry file path." }
+                }
+            },
+            render: (_args, value) => textBlock("OK: deleted " + value.file)
+        },
+        isConcurrencySafe: () => false,
+        async execute(args, exec) {
+            const memo = engineFor(exec, config);
+            const file = await memo.delete(args.commit_hash);
+            return { file };
+        },
+        presentCall: (args) => ({
+            card: "generic",
+            title: "Delete memory " + args.commit_hash.slice(0, 8),
+            kind: "other"
+        })
+    }));
+}
+/**
+ * Register the always-on memory workflow rules (the equivalent of gitmemo's
+ * agents-template.md). This section is part of every session's system prompt,
+ * so the rules cannot be missed; the mem_* tool descriptions carry the
+ * argument contract for each operation.
+ */
+function registerPromptSection(ctx) {
+    ctx.systemPrompt.section({
+        name: "memory:gitmemo",
+        order: 150,
+        text: [
+            "This deployment provides gitmemo long-term memory: a local .mem git repository at the project root stores past task outcomes as markdown entries; git is the only dependency. Use the dedicated tools only (mem_search / mem_read / mem_write / mem_delete — all auto-initialize); never shell out to git or read .mem files directly.",
+            "- BEFORE WORK — search: extract 3-5 keywords from the user request and run mem_search. If more than 5 relevant hits appear, select only the 5 most likely (keyword overlap, title specificity, recency) and mem_read only those; reuse their conclusions when appropriate. If nothing relevant, paginate with skip 20, 40, ...",
+            "- USER UNSATISFIED — delete and rewrite: mem_delete the entry's commit hash, redo the task from the feedback, then mem_write a corrected entry.",
+            "- END-OF-SESSION CHECKPOINT — the ONLY write path: when the conversation is ending, review the whole session and mem_write EVERY completed repo-related task that still lacks a memory and whose outcome is valuable and reusable OR was explicitly asked to be remembered. Never write for pure Q&A, incomplete tasks, non-repo work, or purely operational git actions (commit/push only). Never duplicate an already-written entry; if a stored outcome is outdated, mem_delete it first, then write the corrected entry. Entry title: \"[module] action + object\"; content: markdown with YAML front matter (date, status, repo_branch, mem_branch, related_paths, tags) and Original User Request / AI Understanding / Final Outcome sections."
+        ].join("\n")
+    });
+}
+/**
+ * Seed every new ROOT agent session with the most recent memory titles.
+ * Registered into the agent's own scope, so the block joins only that
+ * session's prompt; subagents (delegationDepth > 0) are skipped, the lookup
+ * is read-only (no .mem auto-init), and failures degrade to a log warning.
+ */
+function registerRecentContext(ctx, config) {
+    if (config.recentContextLimit <= 0)
+        return;
+    ctx.on("agent/created", ({ agent }) => {
+        const header = agent.session?.header;
+        if (header?.cwd === undefined || (header.delegationDepth ?? 0) > 0)
+            return;
+        try {
+            // Synchronous scan: registers the context before the first request assembles.
+            const memo = new GitMemo(config.projectRoot ?? header.cwd, {
+                memDirName: config.memDirName,
+                searchLimit: config.searchLimit,
+                branchAlign: config.branchAlign
+            });
+            const hits = memo.recentSync(config.recentContextLimit);
+            if (hits.length === 0)
+                return;
+            const lines = hits.map((hit) => hit.hash + "|" + hit.title + "|" + hit.date);
+            agent.ctx.systemPrompt.context({
+                name: "memory:gitmemo-recent",
+                order: 400,
+                text: "Recent gitmemo memories from previous sessions (mem_read <hash> for details, mem_search for targeted lookups):\n" + lines.join("\n")
+            });
+        }
+        catch (error) {
+            ctx.logger.warn(`dsh-gitmemo: recent-memory injection skipped for agent "${agent.id}": ${String(error)}`);
+        }
+    });
+}
+/**
+ * Register the plugin: tools, always-on rules, and session-start seed.
+ * @param ctx - registrant context carrying the host tool/prompt services.
+ * @param config - plugin configuration (defaults applied by the loader).
+ */
+async function apply(ctx, config = {}) {
+    const resolved = {
+        memDirName: config.memDirName ?? ".mem",
+        searchLimit: config.searchLimit ?? 20,
+        branchAlign: config.branchAlign ?? true,
+        recentContextLimit: config.recentContextLimit ?? 5,
+        projectRoot: config.projectRoot
+    };
+    registerMemTools(ctx, resolved);
+    registerPromptSection(ctx);
+    registerRecentContext(ctx, resolved);
+}
+export { Config, apply, inject, name };

package/lib/mem.d.ts

@@ -0,0 +1,106 @@
+/** Per-invocation engine options. */
+export interface GitMemoConfig {
+    /** Name of the memory repository directory at the project root. Default ".mem". */
+    memDirName?: string;
+    /** Maximum number of search hits returned per call. Default 20. */
+    searchLimit?: number;
+    /** Whether `.mem` branch follows the project branch on write. Default true. */
+    branchAlign?: boolean;
+    /** Per git subprocess timeout in milliseconds. Default 60000. */
+    gitTimeoutMs?: number;
+    /** Cap on git-log batches scanned by one search call. Default 200. */
+    maxSearchBatches?: number;
+}
+/** One search hit, formatted `hash|title|date` like the original script. */
+export interface SearchHit {
+    hash: string;
+    title: string;
+    date: string;
+}
+export interface WriteOptions {
+    /** Short "[module] action + object" title (required). */
+    title: string;
+    /** Entry markdown; provide exactly one of content / contentFile / file. */
+    content?: string;
+    /** Path to a file holding the entry markdown (temp file or an existing .mem/entries path). */
+    contentFile?: string;
+    /** Existing entry path to commit in place: `entries/foo.md`, `.mem/entries/foo.md`, or an absolute path under .mem. */
+    file?: string;
+    /** Optional single-line commit body. */
+    body?: string;
+    /** Optional path to a file holding the commit body. */
+    bodyFile?: string;
+}
+export interface WriteResult {
+    hash: string;
+    file: string;
+}
+export interface SearchResult {
+    mode: "and" | "or";
+    results: SearchHit[];
+}
+/** True when a path points inside (or at) the memory entries directory. */
+declare function isEntriesPath(memRoot: string, full: string): boolean;
+/**
+ * Git-backed long-term memory engine operating on one project root.
+ */
+export declare class GitMemo {
+    readonly root: string;
+    readonly memDir: string;
+    private readonly config;
+    constructor(root: string, config?: GitMemoConfig);
+    /** The current branch of a git work tree, "main" when detached/unavailable. */
+    private currentBranch;
+    private projectBranch;
+    private memBranch;
+    /**
+     * Initialize the memory repo when missing (git init + .gitkeep commit).
+     * Idempotent; every other operation auto-initializes.
+     */
+    init(): Promise<string>;
+    /** Align the memory repo branch with the project branch (create if needed). */
+    private syncBranch;
+    /**
+     * Search past memories.
+     * @param keywords - comma-separated keywords.
+     * @param skip - pagination offset (default 0).
+     * @param mode - "and" (strict), "or" (broad), or "auto" (AND first, OR fallback).
+     */
+    search(keywords: string, skip?: number, mode?: "and" | "or" | "auto"): Promise<SearchResult>;
+    private runSearchMode;
+    /**
+     * List the most recent memory entries across all branches, newest first.
+     * Used to seed a new session's system prompt with a compact overview.
+     * @param limit - maximum number of entries to return (0 returns none).
+     */
+    recent(limit: number): Promise<SearchHit[]>;
+    /** Active (non-deleted) entry files at HEAD. */
+    private activeEntries;
+    /** Shared git-log scan: keyword-grep optional, active-entry filtering, skip/limit. */
+    private scanLog;
+    /**
+     * Synchronous variant of {@link recent} for the session-start injection
+     * path: blocks until the memory repo is scanned so the system-prompt
+     * context can be registered before the first request assembles.
+     */
+    recentSync(limit: number): SearchHit[];
+    private acceptRecord;
+    /** Resolve the entry file touched by a commit (first file under entries/). */
+    private entryFileFromCommit;
+    /** Read one memory entry by commit hash. */
+    read(commitHash: string): Promise<{
+        file: string;
+        content: string;
+    }>;
+    /**
+     * Write a memory entry.
+     * Mirrors mem.sh write: commit a markdown entry under entries/ with an
+     * optional body, aligning the .mem branch with the project branch first.
+     */
+    write(options: WriteOptions): Promise<WriteResult>;
+    /** Delete a memory entry by commit hash. */
+    delete(commitHash: string): Promise<string>;
+}
+/** Initialize the memory repo when missing. */
+export declare function ensureInit(memDir: string, gitTimeoutMs?: number): Promise<void>;
+export { isEntriesPath };