myagentmemory 0.4.12 → 0.4.13

package/README.md

@@ -1,10 +1,29 @@
 # agent-memory
 
-Persistent memory for coding agents — [Claude Code](https://claude.ai/code), [OpenAI Codex](https://github.com/openai/codex), Cursor, and Agent (Cursor CLI). Semantic search powered by [qmd](https://github.com/tobi/qmd).
+**Persistent memory for AI coding agents.** Give [Claude Code](https://claude.ai/code), [OpenAI Codex](https://github.com/openai/codex), [Cursor](https://cursor.com), and Agent (Cursor CLI) a memory that survives across sessions — long-term facts, daily logs, topic notes, and a scratchpad checklist, stored as plain markdown and searchable with [qmd](https://github.com/tobi/qmd)-powered semantic search.
 
-Thanks to https://github.com/skyfallsin/pi-mem for inspiration.
+[![npm version](https://img.shields.io/npm/v/myagentmemory?color=cb3837&logo=npm)](https://www.npmjs.com/package/myagentmemory)
+[![npm downloads](https://img.shields.io/npm/dm/myagentmemory?color=cb3837&logo=npm)](https://www.npmjs.com/package/myagentmemory)
+[![license](https://img.shields.io/npm/l/myagentmemory)](LICENSE)
+[![website](https://img.shields.io/badge/website-jayzeng.github.io%2Fagentmemory-0d9b7a)](https://jayzeng.github.io/agentmemory/)
 
-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.
+[Website and quickstart](https://jayzeng.github.io/agentmemory/) · [Install](#installation) · [CLI commands](#cli-commands) · [How it works](#how-it-works)
+
+## Why agent-memory?
+
+Coding agents forget everything between sessions. `agent-memory` gives them a durable, local-first memory so they stop re-learning your stack, your preferences, and past decisions on every run.
+
+- **Persistent project memory** — decisions, preferences, and project context carry across sessions instead of starting cold.
+- **Plain Markdown, local-first** — every memory is a readable, git-friendly file on disk. No database, cloud service, or lock-in.
+- **Optional semantic search** — [qmd](https://github.com/tobi/qmd) adds keyword, semantic, and hybrid search across memory files.
+- **Explicit retrieval** — skills load base context at session start and search for related memories when a task needs them.
+- **Shared across agents** — Claude Code, Codex, Cursor, and Agent can use the same store.
+
+> **Naming:** `agentmemory` is the GitHub repo (and Homebrew tap), `myagentmemory` is the npm package, and `agent-memory` is the installed CLI binary. Also known as *coding agent memory* or *AI coding memory*.
+
+### Product boundary
+
+AgentMemory is a local Markdown store with a CLI, optional qmd search, and agent skills. It is not a Python SDK, vector database, or knowledge graph. The Markdown files remain the source of truth.
 
 ## Installation
 
@@ -13,7 +32,7 @@ Long-term facts, daily logs, topic/event notes, and a scratchpad checklist store
 brew tap jayzeng/agentmemory https://github.com/jayzeng/agentmemory
 brew install jayzeng/agentmemory/agent-memory
 
-# Install the CLI globally
+# Install the portable CLI globally (Node.js 20+; macOS, Linux, or Windows)
 npm install -g myagentmemory
 
 # If you hit SSL errors due to corporate MITM/inspection, try:
@@ -33,11 +52,9 @@ agent-memory install-skills
 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.
+The npm package installs a platform-neutral Node.js executable. The optional Homebrew and `build:cli` paths use a native binary built for the current platform.
 
-This installs:
+`install-skills` writes a SKILL.md into each agent's config directory:
 - `~/.claude/skills/agent-memory/SKILL.md` — Claude Code skill
 - `~/.codex/skills/agent-memory/SKILL.md` — Codex skill
 - `~/.cursor/skills/agent-memory/SKILL.md` — Cursor skill
@@ -47,6 +64,10 @@ This installs:
 - `%USERPROFILE%\.cursor\skills\agent-memory\SKILL.md` — Cursor skill (Windows)
 - `%USERPROFILE%\.agents\skills\agent-memory\SKILL.md` — Agent CLI skill (Windows)
 
+### 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.
+
 ### Optional: Enable search with qmd
 
 When qmd is installed, the collection is automatically set up via `agent-memory init`.
@@ -65,22 +86,21 @@ Without qmd, all core tools (write/read/scratchpad) work normally. Only `memory_
 ## Architecture
 
 ```
-  ┌──────────────┐
-  │  src/core.ts │  ← all logic (paths, truncation, scratchpad,
-  │              │    context builder, qmd, tool functions)
-  └──────┬───────┘
-         │
-    ┌────┴─────────────────┐
-    ▼                      ▼
-  ┌──────────┐   ┌──────────────┐
-  │ src/     │   │ skills/      │
-  │ cli.ts   │   │ ├─ claude-code/SKILL.md
-  │          │   │ ├─ codex/SKILL.md
-  │          │   │ ├─ cursor/SKILL.md
-  │          │   │ └─ agent/SKILL.md
-  └──────────┘   └──────────────┘
-   CLI binary     instruction files
-   `agent-memory` that invoke CLI
+  ┌───────────────┐
+  │  src/core.ts  │  ← all logic: paths, truncation, scratchpad,
+  └───────┬───────┘     context builder, qmd, tool functions
+          │
+     ┌────┴─────┐
+     ▼          ▼
+  ┌─────────┐   ┌─────────────────────────┐
+  │ src/    │   │ skills/                 │
+  │ cli.ts  │   │ ├─ claude-code/SKILL.md │
+  │         │   │ ├─ codex/SKILL.md       │
+  │         │   │ ├─ cursor/SKILL.md      │
+  │         │   │ └─ agent/SKILL.md       │
+  └─────────┘   └─────────────────────────┘
+   CLI command    instruction files
+  `agent-memory`  that invoke the CLI
 ```
 
 The memory directory defaults to `~/.agent-memory/`. Override with `AGENT_MEMORY_DIR` env var or `--dir` flag.
@@ -89,8 +109,8 @@ 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\|topic> --content <text> [--mode append\|overwrite] [--topic <name>] [--date YYYY-MM-DD]` | Write to memory files |
+| `agent-memory context [--query <text>] [--no-search]` | Build context and optionally include qmd matches for a query |
+| `agent-memory write --target <long_term\|daily\|topic> --content <text> [--mode append\|overwrite] [--source-uri <uri>] [--topic <name>] [--date YYYY-MM-DD]` | Write to memory files with optional provenance |
 | `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 |
@@ -115,14 +135,14 @@ If the first search doesn't find what you need, try rephrasing or switching mode
 
 ```
 ~/.agent-memory/
-  MEMORY.md              # Curated long-term memory
-  SCRATCHPAD.md           # Checklist of things to fix/remember
+  MEMORY.md                # Curated long-term memory
+  SCRATCHPAD.md            # Checklist of things to fix/remember
   daily/
-    2026-02-15.md         # Daily append-only log
+    2026-02-15.md          # Daily append-only log
     2026-02-14.md
     ...
   topics/
-    auth.md               # Topic/event log linked back to daily entries
+    auth.md                # Topic/event log linked back to daily entries
 ```
 
 ## Topic notes
@@ -139,25 +159,31 @@ agent-memory read --target topics
 
 ### Context injection
 
-Before every agent turn, the following are injected into the system prompt (in priority order):
+The context builder emits the following sections in priority order. Installed skills load base context at session start; callers can optionally supply `--query` to add relevant qmd results:
 
 1. **Open scratchpad items** (up to 2K chars)
 2. **Recent topic entries** (up to 2K chars) — most recent topic notes with backlinks
-3. **Today's daily log** (up to 3K chars, tail)
+3. **Today's daily log** (up to 3K chars, head + 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.
+Total output, including headings and truncation notices, is hard-capped at 16,000 characters. Explicitly untrusted, expired, superseded, revoked, or retired blocks are excluded; legacy secret-like values are redacted before injection. When qmd is unavailable, the relevant-memory step is skipped and the rest still works.
 
-For Claude Code, context is injected via the `!`agent-memory context`` syntax in the SKILL.md. For Codex, Cursor, and Agent, the agent runs `agent-memory context` at session start.
+Claude Code loads base context through the skill's shell injection. Codex, Cursor, and Agent run the same base command at session start. The bundled skills use explicit search when a task relates to prior work; they make no host-level guarantee of automatic retrieval.
 
 ### Selective injection
 
-When qmd is available, the system automatically searches memory using the user's prompt on demand (CLI). The top 3 keyword results are injected alongside the standard context.
+When qmd is available and `context --query` is supplied, the CLI sanitizes the query, limits it to 200 characters, and includes the top three keyword results with the standard context. Programmatic integrations should spawn the CLI with an argument array so query text is not evaluated by a shell.
 
 The search has a 3-second timeout and fails silently. If qmd is down or the query returns nothing, injection falls back to the standard behavior.
 
+### Provenance, temporal state, and secret screening
+
+`write --source-uri <uri>` stores an addressable `Source:` line with the entry. Plain-Markdown compatibility is retained: complete write entries containing standalone header metadata lines such as `Trust: untrusted`, `Status: expired`, `Status: superseded`, `Status: revoked`, or `Status: retired` are kept on disk but omitted from direct, distilled, and auto-retrieved agent context. A standalone past `Valid until: YYYY-MM-DD` line is also honored. These phrases inside ordinary prose are not treated as metadata.
+
+Writes screen a bounded set of high-confidence credential shapes and replace matching values with `[REDACTED_SECRET]` before persistence. Context rendering applies the same screening to legacy files. This is defense in depth, not a secrets vault; avoid passing real credentials in command arguments or memory content.
+
 ### Tags and links
 
 Use `#tags` and `[[wiki-links]]` in memory content to improve searchability:
@@ -192,6 +218,14 @@ These are content conventions, not enforced metadata. qmd's full-text indexing m
 # Unit tests (no LLM, no qmd — fast, deterministic)
 bun test test/unit.test.ts
 bun test test/cli.test.ts
+
+# External-feedback dataset and deterministic capability probes
+bun run build:eval
+bun run test:eval
+bun run eval:feedback
+
+# Optional: add isolated live qmd multilingual retrieval probes
+bun run eval:feedback --live-qmd
 ```
 
 ### Test levels
@@ -200,6 +234,7 @@ bun test test/cli.test.ts
 |-------|------|-------------|---------------|
 | Unit | `test/unit.test.ts` | None | Utilities, scratchpad parsing, context builder, qmd helpers, tool functions |
 | CLI | `test/cli.test.ts` | None | CLI commands, subprocess integration |
+| Feedback eval | `test/eval.test.ts`, `eval/` | qmd optional | External feedback, capability gaps, multilingual retrieval, and qualitative boundaries |
 
 ## Development
 
@@ -218,7 +253,7 @@ agent-memory install-skills
 
 ```bash
 # Confirm package name is available
-npm view agent-memory
+npm view myagentmemory
 
 # Bump version (choose patch/minor/major)
 npm version patch
@@ -227,13 +262,23 @@ npm version patch
 npm publish --access public
 ```
 
+### Repository assets (maintainers)
+
+- **Social preview image:** `.github/assets/social-preview.png` (1280×640)
+- **Release notes template:** `.github/release.yml` (used by GitHub auto-generated release notes)
+- **Landing page source:** `docs/index.html` (deployed by `.github/workflows/deploy-pages.yml`)
+
+## Acknowledgments
+
+Inspired by [skyfallsin/pi-mem](https://github.com/skyfallsin/pi-mem). Semantic search is powered by [qmd](https://github.com/tobi/qmd).
+
 ## Changelog
 
-### 0.5.0
+### 0.4.12
 
 - **Removed pi extension**: Removed `index.ts` and all pi-specific code (`@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, `@sinclair/typebox` peer dependencies).
 - **Standalone tool functions**: Extracted `memoryWrite()`, `memoryRead()`, `scratchpadAction()`, `memorySearch()` into `src/core.ts` as standalone functions usable without any framework.
-- **Renamed package**: `pi-memory` → `agent-memory`.
+- **Renamed package**: `pi-memory` → `myagentmemory` (npm); the CLI binary is `agent-memory`.
 - **Renamed env var**: `PI_MEMORY_QMD_UPDATE` → `AGENT_MEMORY_QMD_UPDATE` (old name still works as fallback).
 - **Default memory directory**: Now always `~/.agent-memory/`.
 - **Removed pi-specific tests**: Deleted `test/e2e.ts`, `test/eval-recall.ts`, `test/unit.ts`.

package/dist/cli.js

@@ -18,8 +18,17 @@
  *   --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, distilMemories, ensureDirs, ensureQmdAvailableForSync, ensureQmdAvailableForUpdate, getCollectionName, getDailyDir, getMemoryDir, getMemoryFile, getQmdEmbedMode, getQmdHealth, getQmdResultPath, getQmdResultText, getScratchpadFile, getTopicsDir, installSkills, memoryWrite, nowTimestamp, parseScratchpad, probeEmbeddings, readFileSafe, redactSecrets, runQmdEmbedDetached, runQmdSearch, runQmdSync, runQmdUpdateNow, scheduleQmdUpdate, searchRelevantMemories, serializeScratchpad, setupQmdCollection, slugifyTopic, todayStr, topicPath, uninstallSkills, } from "./core.js";
+function readPackageVersion() {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+        return typeof packageJson.version === "string" ? packageJson.version : "dev";
+    }
+    catch {
+        return "dev";
+    }
+}
+const VERSION = typeof __VERSION__ !== "undefined" ? __VERSION__ : readPackageVersion();
 function parseArgs(argv) {
     const flags = {};
     const positional = [];
@@ -83,8 +92,11 @@ function exitError(message, json) {
 async function cmdContext(flags) {
     const json = hasFlag(flags, "json");
     const noSearch = hasFlag(flags, "no-search");
+    const query = getFlag(flags, "query") ?? "";
     ensureDirs();
-    const searchResults = noSearch ? "" : await searchRelevantMemories("");
+    if (!noSearch && query)
+        await ensureQmdAvailableForSync();
+    const searchResults = noSearch ? "" : await searchRelevantMemories(query);
     const context = buildMemoryContext(searchResults);
     if (json) {
         output({ context, directory: getMemoryDir() }, true);
@@ -102,68 +114,28 @@ async function cmdWrite(flags) {
     const mode = getFlag(flags, "mode") ?? "append";
     const topic = getFlag(flags, "topic");
     const date = getFlag(flags, "date");
+    const sourceUri = getFlag(flags, "source-uri");
     if (!["long_term", "daily", "topic"].includes(target)) {
         exitError("--target must be 'long_term', 'daily', or 'topic' (default: daily)", json);
     }
+    if (!["append", "overwrite"].includes(mode)) {
+        exitError("--mode must be 'append' or 'overwrite'", 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;
-    }
-    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) ?? "";
-    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);
+    const result = await memoryWrite({
+        target: target,
+        content,
+        mode: mode,
+        sessionId: "cli",
+        topic,
+        date,
+        sourceUri,
+    });
+    if (result.isError)
+        exitError(result.text.replace(/^Error:\s*/, ""), json);
+    output(json ? { ok: true, ...result.details } : result.text.split("\n\n", 1)[0], json);
 }
 async function cmdRead(flags) {
     const json = hasFlag(flags, "json");
@@ -270,7 +242,11 @@ async function cmdScratchpad(flags, positional) {
     ensureDirs();
     const spFile = getScratchpadFile();
     const existing = readFileSafe(spFile) ?? "";
-    let items = parseScratchpad(existing);
+    let items = parseScratchpad(existing).map((item) => ({
+        ...item,
+        text: redactSecrets(item.text).content,
+        meta: redactSecrets(item.meta).content,
+    }));
     if (action === "list") {
         if (items.length === 0) {
             output(json ? { items: [], count: 0, open: 0 } : "Scratchpad is empty.", json);
@@ -292,11 +268,12 @@ async function cmdScratchpad(flags, positional) {
         if (!text)
             exitError("--text is required for add", json);
         const ts = nowTimestamp();
-        items.push({ done: false, text: text, meta: `<!-- ${ts} [cli] -->` });
+        const safeText = redactSecrets(text).content;
+        items.push({ done: false, text: safeText, meta: `<!-- ${ts} [cli] -->` });
         fs.writeFileSync(spFile, serializeScratchpad(items), "utf-8");
         await ensureQmdAvailableForUpdate();
         scheduleQmdUpdate();
-        output(json ? { ok: true, action, text } : `Added: - [ ] ${text}`, json);
+        output(json ? { ok: true, action, text: safeText } : `Added: - [ ] ${safeText}`, json);
         return;
     }
     if (action === "done" || action === "undo") {
@@ -561,11 +538,18 @@ async function cmdStatus(flags) {
     const qmdFound = await detectQmd();
     let hasCollection = false;
     let health = null;
+    let embeddings = "n/a";
     if (qmdFound) {
         hasCollection = await checkCollection();
         if (hasCollection) {
             await ensureQmdAvailableForSync();
             health = await getQmdHealth();
+            // A live semantic probe confirms embeddings are actually usable, but
+            // it costs a real qmd query (and a possible model load), so it's
+            // opt-in — the cheap pending-embed count below covers the common case.
+            if (hasFlag(flags, "probe")) {
+                embeddings = await probeEmbeddings();
+            }
         }
     }
     const embedMode = getQmdEmbedMode();
@@ -588,6 +572,7 @@ async function cmdStatus(flags) {
                 available: qmdFound,
                 collection: hasCollection ? getCollectionName() : null,
                 health,
+                embeddings,
             },
             embedMode,
         }, true);
@@ -617,6 +602,14 @@ async function cmdStatus(flags) {
             console.log(`qmd: available`);
             console.log(`Collection '${getCollectionName()}': ${hasCollection ? "configured" : "not configured — run: agent-memory init"}`);
             console.log(`Embed mode: ${embedMode}`);
+            if (hasCollection && embeddings !== "n/a") {
+                const embLabel = embeddings === "ready"
+                    ? "ready"
+                    : embeddings === "missing"
+                        ? "missing — run: agent-memory sync"
+                        : "unknown (could not verify within probe timeout)";
+                console.log(`Embeddings (semantic/deep search): ${embLabel}`);
+            }
             if (health) {
                 if (health.totalFiles !== null)
                     console.log(`Files indexed: ${health.totalFiles}`);
@@ -671,15 +664,15 @@ Commands:
   version     Show binary version
   install-skills  Install (or --uninstall) bundled skills
   uninstall-skills  Uninstall bundled skills
-  context     Build & print context injection string
-  write       Write to memory files (default: daily)
+  context     Build context; optionally retrieve memories with --query
+  write       Write to memory files (default: daily; optional --source-uri)
   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
+  status      Show configuration and status (--probe for a live embeddings check)
 
 Global flags:
   --dir <path>   Override memory directory
@@ -688,7 +681,7 @@ 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 long_term --content "User prefers dark mode" --source-uri "session://agent/turn/12"
   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
@@ -700,7 +693,7 @@ Examples:
   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 context --query "database choice"
   agent-memory sync
   agent-memory status --json`);
 }

package/dist/core.d.ts

@@ -40,6 +40,13 @@ export interface PreviewResult {
     previewLines: number;
     previewChars: number;
 }
+/** Redact common credential shapes before content reaches disk or agent context. */
+export declare function redactSecrets(content: string): {
+    content: string;
+    redacted: boolean;
+};
+/** Apply trust, lifecycle, and secret policy to complete logical write entries. */
+export declare function filterMemoryForContext(content: string, now?: Date): string;
 export declare function truncateLines(lines: string[], maxLines: number, mode: TruncateMode): {
     lines: string[];
     truncated: boolean;
@@ -166,6 +173,7 @@ export declare function searchRelevantMemories(prompt: string): Promise<string>;
 export interface QmdSearchResult {
     path?: string;
     file?: string;
+    context?: string;
     score?: number;
     content?: string;
     chunk?: string;
@@ -175,10 +183,21 @@ export interface QmdSearchResult {
 }
 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<{
+export declare function runQmdSearch(mode: "keyword" | "semantic" | "deep", query: string, limit: number, options?: {
+    signal?: AbortSignal;
+}): Promise<{
     results: QmdSearchResult[];
     stderr: string;
 }>;
+/**
+ * Best-effort check of whether vector embeddings are actually usable for
+ * semantic/deep search right now. Runs a tiny semantic probe and looks for
+ * qmd's "need embeddings" warning. Bounded by a short timeout because the very
+ * first semantic query can trigger a model download — returns "unknown" rather
+ * than blocking on it. "ready" means the probe ran without the warning; it does
+ * not prove the index has content.
+ */
+export declare function probeEmbeddings(): Promise<"ready" | "missing" | "unknown">;
 export interface ToolResult {
     text: string;
     details: Record<string, unknown>;
@@ -191,6 +210,7 @@ export declare function memoryWrite(params: {
     sessionId?: string;
     topic?: string;
     date?: string;
+    sourceUri?: string;
 }): Promise<ToolResult>;
 export declare function scratchpadAction(params: {
     action: "add" | "done" | "undo" | "clear_done" | "list";