myagentmemory 0.4.8 → 0.4.11

package/README.md

@@ -4,11 +4,15 @@ Persistent memory for coding agents — [Claude Code](https://claude.ai/code), [
 
 Thanks to https://github.com/skyfallsin/pi-mem for inspiration.
 
-Long-term facts, daily logs, and a scratchpad checklist stored as plain markdown files. Optional qmd integration adds keyword, semantic, and hybrid search across all memory files, plus automatic selective injection of relevant past memories into every turn.
+Long-term facts, daily logs, topic/event notes, and a scratchpad checklist stored as plain markdown files. Optional qmd integration adds keyword, semantic, and hybrid search across all memory files, plus automatic selective injection of relevant past memories into every turn.
 
 ## Installation
 
 ```bash
+# Homebrew (macOS)
+brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory
+brew install jayzeng/agentmemory/agent-memory
+
 # Install the CLI globally
 npm install -g myagentmemory
 
@@ -24,8 +28,15 @@ agent-memory init
 
 # Install skill files for Claude Code, Codex, Cursor, and Agent
 agent-memory install-skills
+
+# Uninstall skill files
+agent-memory uninstall-skills
 ```
 
+### Pi users
+
+If you're on Pi and prefer a native extension, use `pi-memory` (https://github.com/jayzeng/pi-memory) instead of installing this skill. The CLI + skill workflow here is the cross-platform alternative, and works fine on Pi without any extension.
+
 This installs:
 - `~/.claude/skills/agent-memory/SKILL.md` — Claude Code skill
 - `~/.codex/skills/agent-memory/SKILL.md` — Codex skill
@@ -79,11 +90,12 @@ The memory directory defaults to `~/.agent-memory/`. Override with `AGENT_MEMORY
 | Command | Purpose |
 |---------|---------|
 | `agent-memory context [--no-search]` | Build & print context injection string to stdout |
-| `agent-memory write --target <long_term\|daily> --content <text> [--mode append\|overwrite]` | Write to memory files |
-| `agent-memory read --target <long_term\|scratchpad\|daily\|list> [--date YYYY-MM-DD]` | Read memory files |
+| `agent-memory write --target <long_term\|daily\|topic> --content <text> [--mode append\|overwrite] [--topic <name>] [--date YYYY-MM-DD]` | Write to memory files |
+| `agent-memory read --target <long_term\|scratchpad\|daily\|list\|topic\|topics> [--date YYYY-MM-DD] [--topic <name>]` | Read memory files |
 | `agent-memory scratchpad <add\|done\|undo\|clear_done\|list> [--text <text>]` | Manage checklist |
 | `agent-memory search --query <text> [--mode keyword\|semantic\|deep] [--limit N]` | Search via qmd |
 | `agent-memory install-skills` | Install bundled SKILL.md files into local agent directories |
+| `agent-memory uninstall-skills` | Uninstall bundled SKILL.md files from local agent directories |
 | `agent-memory init` | Create dirs, detect qmd, setup collection |
 | `agent-memory status` | Show config, qmd status, file counts |
 
@@ -109,6 +121,18 @@ If the first search doesn't find what you need, try rephrasing or switching mode
     2026-02-15.md         # Daily append-only log
     2026-02-14.md
     ...
+  topics/
+    auth.md               # Topic/event log linked back to daily entries
+```
+
+## Topic notes
+
+Topic files are for event- or theme-based tracking across days. Each topic entry includes a `Daily: [[YYYY-MM-DD]]` backlink so you can jump from the topic to the full daily log.
+
+```bash
+agent-memory write --target topic --topic "auth" --content "JWT refresh rolled out to edge #auth"
+agent-memory read --target topic --topic "auth"
+agent-memory read --target topics
 ```
 
 ## How it works
@@ -118,10 +142,11 @@ If the first search doesn't find what you need, try rephrasing or switching mode
 Before every agent turn, the following are injected into the system prompt (in priority order):
 
 1. **Open scratchpad items** (up to 2K chars)
-2. **Today's daily log** (up to 3K chars, tail)
-3. **Relevant memories via qmd search** (up to 2.5K chars) — searches using the user's current prompt to surface related past context
-4. **MEMORY.md** (up to 4K chars, middle-truncated)
-5. **Yesterday's daily log** (up to 3K chars, tail — lowest priority, trimmed first)
+2. **Recent topic entries** (up to 2K chars) — most recent topic notes with backlinks
+3. **Today's daily log** (up to 3K chars, tail)
+4. **Relevant memories via qmd search** (up to 2.5K chars) — searches using the user's current prompt to surface related past context
+5. **MEMORY.md** (up to 4K chars, middle-truncated)
+6. **Yesterday's daily log** (up to 3K chars, tail — lowest priority, trimmed first)
 
 Total injection is capped at 16K chars. When qmd is unavailable, step 3 is skipped and the rest works as before.
 

package/dist/cli.d.ts

@@ -4,7 +4,7 @@
  *
  * Subcommands:
  *   version    — Print binary version
- *   install-skills — Install SKILL.md files into local agent directories
+ *   install-skills — Install (or --uninstall) SKILL.md files into local agent directories
  *   context    — Build & print context injection string to stdout
  *   write      — Write to memory files
  *   read       — Read memory files

package/dist/cli.js

@@ -4,7 +4,7 @@
  *
  * Subcommands:
  *   version    — Print binary version
- *   install-skills — Install SKILL.md files into local agent directories
+ *   install-skills — Install (or --uninstall) SKILL.md files into local agent directories
  *   context    — Build & print context injection string to stdout
  *   write      — Write to memory files
  *   read       — Read memory files
@@ -18,8 +18,8 @@
  *   --json         Machine-readable JSON output
  */
 import * as fs from "node:fs";
+import { _setBaseDir, buildMemoryContext, checkCollection, dailyPath, detectQmd, distilMemories, ensureDirs, ensureQmdAvailableForSync, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdEmbedMode, getQmdHealth, getQmdResultPath, getQmdResultText, getScratchpadFile, getTopicsDir, installSkills, nowTimestamp, parseScratchpad, readFileSafe, runQmdEmbedDetached, runQmdSearch, runQmdSync, runQmdUpdateNow, scheduleQmdUpdate, searchRelevantMemories, serializeScratchpad, setupQmdCollection, slugifyTopic, todayStr, topicPath, uninstallSkills, } from "./core.js";
 const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : "dev";
-import { _setBaseDir, buildMemoryContext, checkCollection, dailyPath, detectQmd, ensureDirs, ensureQmdAvailableForSync, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdEmbedMode, getQmdHealth, getQmdResultPath, getQmdResultText, getScratchpadFile, installSkills, nowTimestamp, parseScratchpad, readFileSafe, runQmdEmbedDetached, runQmdSearch, runQmdSync, runQmdUpdateNow, scheduleQmdUpdate, searchRelevantMemories, serializeScratchpad, setupQmdCollection, todayStr, } from "./core.js";
 function parseArgs(argv) {
     const flags = {};
     const positional = [];
@@ -97,11 +97,13 @@ async function cmdContext(flags) {
 }
 async function cmdWrite(flags) {
     const json = hasFlag(flags, "json");
-    const target = getFlag(flags, "target");
+    const target = getFlag(flags, "target") ?? "daily";
     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);
+    const topic = getFlag(flags, "topic");
+    const date = getFlag(flags, "date");
+    if (!["long_term", "daily", "topic"].includes(target)) {
+        exitError("--target must be 'long_term', 'daily', or 'topic' (default: daily)", json);
     }
     if (!content) {
         exitError("--content is required", json);
@@ -122,6 +124,29 @@ async function cmdWrite(flags) {
             : `Appended to daily log: ${filePath}`, json);
         return;
     }
+    if (target === "topic") {
+        if (!topic) {
+            exitError("--topic is required when --target is 'topic'", json);
+        }
+        const slug = slugifyTopic(topic);
+        if (!slug) {
+            exitError("--topic must include at least one letter or number", json);
+        }
+        const filePath = topicPath(slug);
+        const existing = readFileSafe(filePath) ?? "";
+        const linkDate = date?.trim() || todayStr();
+        const header = `# Topic: ${topic}\n\n<!-- created: ${ts} [${sid}] -->\n`;
+        const separator = existing.trim() ? "\n\n" : "";
+        const base = existing.trim() ? existing : header.trimEnd();
+        const stamped = `<!-- ${ts} [${sid}] -->\n${content.trim()}\nDaily: [[${linkDate}]]`;
+        fs.writeFileSync(filePath, `${base}${separator}${stamped}`, "utf-8");
+        await ensureQmdAvailableForUpdate();
+        scheduleQmdUpdate();
+        output(json
+            ? { ok: true, path: filePath, target, mode: "append", timestamp: ts, topic, slug, date: linkDate }
+            : `Appended to topic: ${filePath}`, json);
+        return;
+    }
     // long_term
     const memFile = getMemoryFile();
     const existing = readFileSafe(memFile) ?? "";
@@ -144,8 +169,9 @@ 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);
+    const topic = getFlag(flags, "topic");
+    if (!target || !["long_term", "scratchpad", "daily", "list", "topic", "topics"].includes(target)) {
+        exitError("--target must be 'long_term', 'scratchpad', 'daily', 'list', 'topic', or 'topics'", json);
     }
     ensureDirs();
     if (target === "list") {
@@ -181,6 +207,42 @@ async function cmdRead(flags) {
         output(json ? { content, date: d, path: filePath } : content, json);
         return;
     }
+    if (target === "topics") {
+        try {
+            const files = fs
+                .readdirSync(getTopicsDir())
+                .filter((f) => f.endsWith(".md"))
+                .sort()
+                .reverse();
+            if (json) {
+                output({ files }, true);
+            }
+            else if (files.length === 0) {
+                console.log("No topics found.");
+            }
+            else {
+                console.log(`Topics:\n${files.map((f) => `- ${f}`).join("\n")}`);
+            }
+        }
+        catch {
+            output(json ? { files: [] } : "No topics directory.", json);
+        }
+        return;
+    }
+    if (target === "topic") {
+        if (!topic) {
+            exitError("--topic is required when --target is 'topic'", json);
+        }
+        const slug = slugifyTopic(topic);
+        const filePath = topicPath(slug);
+        const content = readFileSafe(filePath);
+        if (!content) {
+            output(json ? { content: null, topic } : `No topic file found for ${topic}.`, json);
+            return;
+        }
+        output(json ? { content, topic, slug, path: filePath } : content, json);
+        return;
+    }
     if (target === "scratchpad") {
         const content = readFileSafe(getScratchpadFile());
         if (!content?.trim()) {
@@ -324,6 +386,27 @@ async function cmdSearch(flags) {
 }
 function cmdInstallSkills(flags) {
     const json = hasFlag(flags, "json");
+    const uninstall = hasFlag(flags, "uninstall");
+    if (uninstall) {
+        const report = uninstallSkills();
+        if (!report.ok) {
+            exitError(report.error ?? "Failed to uninstall skills.", json);
+        }
+        if (json) {
+            output(report, true);
+            return;
+        }
+        for (const item of report.removed) {
+            console.log(`Uninstalled ${item.label}: ${item.path}`);
+        }
+        for (const item of report.skipped) {
+            console.log(`Skipping ${item.label} (${item.reason})`);
+        }
+        if (report.removed.length === 0) {
+            console.log("No skills were installed.");
+        }
+        return;
+    }
     const report = installSkills();
     if (!report.ok) {
         exitError(report.error ?? "Failed to install skills.", json);
@@ -430,7 +513,7 @@ async function cmdInit(flags) {
     }
     else {
         console.log(`Memory directory: ${dir}`);
-        console.log(`  MEMORY.md, SCRATCHPAD.md, daily/ created.`);
+        console.log(`  MEMORY.md, SCRATCHPAD.md, daily/, topics/ created.`);
         if (qmdFound) {
             if (collectionCreated) {
                 console.log(`  qmd collection '${getCollectionName()}' created.`);
@@ -458,6 +541,7 @@ async function cmdStatus(flags) {
     const memFile = getMemoryFile();
     const spFile = getScratchpadFile();
     const dailyDir = getDailyDir();
+    const topicsDir = getTopicsDir();
     const memContent = readFileSafe(memFile);
     const spContent = readFileSafe(spFile);
     let dailyCount = 0;
@@ -467,6 +551,13 @@ async function cmdStatus(flags) {
     catch {
         // directory may not exist
     }
+    let topicCount = 0;
+    try {
+        topicCount = fs.readdirSync(topicsDir).filter((f) => f.endsWith(".md")).length;
+    }
+    catch {
+        // directory may not exist
+    }
     const qmdFound = await detectQmd();
     let hasCollection = false;
     let health = null;
@@ -492,6 +583,7 @@ async function cmdStatus(flags) {
                 openItems: spContent ? parseScratchpad(spContent).filter((i) => !i.done).length : 0,
             },
             dailyLogs: dailyCount,
+            topics: topicCount,
             qmd: {
                 available: qmdFound,
                 collection: hasCollection ? getCollectionName() : null,
@@ -519,6 +611,7 @@ async function cmdStatus(flags) {
             console.log("SCRATCHPAD.md: not created yet");
         }
         console.log(`Daily logs: ${dailyCount} file(s)`);
+        console.log(`Topics: ${topicCount} file(s)`);
         console.log("");
         if (qmdFound) {
             console.log(`qmd: available`);
@@ -542,6 +635,29 @@ async function cmdStatus(flags) {
         }
     }
 }
+async function cmdDistil(flags) {
+    const json = hasFlag(flags, "json");
+    const dryRun = hasFlag(flags, "dry-run");
+    const result = await distilMemories({ dryRun });
+    if (json) {
+        output(result, true);
+    }
+    else {
+        if (result.totalEntries === 0) {
+            console.log(result.output.trim());
+            return;
+        }
+        if (dryRun) {
+            console.log("--- Dry run (MEMORY.md not modified) ---\n");
+        }
+        console.log(result.output.trim());
+        console.log("");
+        console.log(`Distilled ${result.totalEntries} entries from ${result.totalDailyFiles} daily file(s) and ${result.totalTopicFiles} topic file(s), ${result.totalTags} tag(s).`);
+        if (!dryRun) {
+            console.log("MEMORY.md updated.");
+        }
+    }
+}
 // ---------------------------------------------------------------------------
 // Usage
 // ---------------------------------------------------------------------------
@@ -553,12 +669,14 @@ Usage:
 
 Commands:
   version     Show binary version
-  install-skills  Install bundled skills into local agent directories
+  install-skills  Install (or --uninstall) bundled skills
+  uninstall-skills  Uninstall bundled skills
   context     Build & print context injection string
-  write       Write to memory files
+  write       Write to memory files (default: daily)
   read        Read memory files
   scratchpad  Manage checklist items
   search      Search across memory files (requires qmd)
+  distil      Generate compact MEMORY.md index from daily logs + topics
   sync        Re-index and embed all files (requires qmd)
   init        Initialize memory directory and qmd collection
   status      Show configuration and status
@@ -569,15 +687,19 @@ Global flags:
 
 Examples:
   agent-memory init
+  agent-memory write --content "Fixed auth bug in login flow"
   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 write --target topic --topic "auth" --content "Rolled JWT refresh to edge"
   agent-memory read --target long_term
   agent-memory read --target daily --date 2026-02-15
   agent-memory read --target list
+  agent-memory read --target topic --topic "auth"
+  agent-memory read --target topics
   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 distil --dry-run
   agent-memory context --no-search
   agent-memory sync
   agent-memory status --json`);
@@ -620,6 +742,13 @@ async function main() {
         case "install-skills":
             cmdInstallSkills(flags);
             break;
+        case "uninstall-skills":
+            cmdInstallSkills({ ...flags, uninstall: true });
+            break;
+        case "distil":
+        case "distill":
+            await cmdDistil(flags);
+            break;
         case "sync":
             await cmdSync(flags);
             break;

package/dist/core.d.ts

@@ -18,6 +18,8 @@ export declare function getMemoryFile(): string;
 export declare function getScratchpadFile(): string;
 /** Get the current daily log directory path. */
 export declare function getDailyDir(): string;
+/** Get the current topics directory path. */
+export declare function getTopicsDir(): string;
 export declare function ensureDirs(): void;
 export declare function todayStr(): string;
 export declare function yesterdayStr(): string;
@@ -25,6 +27,8 @@ 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 function topicPath(slug: string): string;
+export declare function slugifyTopic(name: string): string;
 export declare const RESPONSE_PREVIEW_MAX_CHARS = 4000;
 export declare const RESPONSE_PREVIEW_MAX_LINES = 120;
 export type TruncateMode = "start" | "end" | "middle";
@@ -132,6 +136,20 @@ export interface InstallSkillsReport {
     error?: string;
 }
 export declare function installSkills(): InstallSkillsReport;
+export interface UninstallSkillsReport {
+    ok: boolean;
+    homeDir?: string;
+    removed: Array<{
+        label: string;
+        path: string;
+    }>;
+    skipped: Array<{
+        label: string;
+        reason: string;
+    }>;
+    error?: string;
+}
+export declare function uninstallSkills(): UninstallSkillsReport;
 export interface QmdHealthInfo {
     totalFiles: number | null;
     vectorsEmbedded: number | null;
@@ -167,10 +185,12 @@ export interface ToolResult {
     isError?: boolean;
 }
 export declare function memoryWrite(params: {
-    target: "long_term" | "daily";
+    target?: "long_term" | "daily" | "topic";
     content: string;
     mode?: "append" | "overwrite";
     sessionId?: string;
+    topic?: string;
+    date?: string;
 }): Promise<ToolResult>;
 export declare function scratchpadAction(params: {
     action: "add" | "done" | "undo" | "clear_done" | "list";
@@ -178,12 +198,62 @@ export declare function scratchpadAction(params: {
     sessionId?: string;
 }): Promise<ToolResult>;
 export declare function memoryRead(params: {
-    target: "long_term" | "scratchpad" | "daily" | "list";
+    target: "long_term" | "scratchpad" | "daily" | "list" | "topic" | "topics";
     date?: string;
+    topic?: string;
 }): Promise<ToolResult>;
 export declare function memorySearch(params: {
     query: string;
     mode?: "keyword" | "semantic" | "deep";
     limit?: number;
 }): Promise<ToolResult>;
+/** Extract #tag patterns, deduplicated and lowercased. */
+export declare function extractTags(content: string): string[];
+/** Extract [[link]] patterns. */
+export declare function extractLinks(content: string): string[];
+/** Extract file-path-like patterns (e.g. src/foo.ts), filtering out URLs. */
+export declare function extractFilePaths(content: string): string[];
+/** Extract backtick-quoted commands. */
+export declare function extractCommands(content: string): string[];
+export interface DailyEntry {
+    date: string;
+    timestamp: string;
+    sessionId: string;
+    content: string;
+    tags: string[];
+    links: string[];
+    filePaths: string[];
+    commands: string[];
+}
+/** Split a daily file on <!-- timestamp --> markers into individual entries. */
+export declare function parseDailyEntries(date: string, content: string): DailyEntry[];
+export interface TopicEntry {
+    topic: string;
+    slug: string;
+    date: string;
+    timestamp: string;
+    sessionId: string;
+    content: string;
+    tags: string[];
+    links: string[];
+    filePaths: string[];
+    commands: string[];
+}
+/** Split a topic file on <!-- timestamp --> markers into entries. */
+export declare function parseTopicEntries(topic: string, slug: string, content: string): TopicEntry[];
+export interface DistilResult {
+    ok: boolean;
+    dryRun: boolean;
+    totalDailyFiles: number;
+    totalTopicFiles: number;
+    totalEntries: number;
+    totalTopicEntries: number;
+    totalTags: number;
+    tagCounts: Record<string, number>;
+    output: string;
+}
+export declare function distilMemories(params?: {
+    dryRun?: boolean;
+    sessionId?: string;
+}): Promise<DistilResult>;
 export {};