open-memex 0.7.0-alpha.8 → 0.7.0

package/src/retrieve/display.ts

@@ -0,0 +1,174 @@
+/**
+ * Display helpers (D68): how memory provenance, age, and state are
+ * rendered on the user-facing surfaces — the `memory_list` inventory an
+ * agent shows its user, and the `open-memex inventory` reports.
+ *
+ * Two rules from the 3-C design (v2) live here:
+ * - The list format is STRUCTURED data (number + id + created= + source=
+ *   + state tags). The plain-language renderings ("you said this",
+ *   "3 days ago") live in the guidance surfaces (tool descriptions,
+ *   SKILL.md, MCP handshake) so an agent rephrases them in the
+ *   conversation's language — the raw enums never get localized or
+ *   reworded inside the data itself.
+ * - Nothing truncates silently: callers pair these lines with the true
+ *   totals so a cut list says so.
+ */
+
+/** Human age for a saved memory: "just now", "3 days ago", else a date. */
+export function relativeTime(ts: number, now = Date.now()): string {
+  if (!ts || Number.isNaN(ts)) return "";
+  const diff = now - ts;
+  if (diff < 0) return "just now";
+  const minute = 60_000;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+  if (diff < minute) return "just now";
+  if (diff < hour) {
+    const n = Math.floor(diff / minute);
+    return `${n} minute${n === 1 ? "" : "s"} ago`;
+  }
+  if (diff < day) {
+    const n = Math.floor(diff / hour);
+    return `${n} hour${n === 1 ? "" : "s"} ago`;
+  }
+  if (diff < 30 * day) {
+    const n = Math.floor(diff / day);
+    return `${n} day${n === 1 ? "" : "s"} ago`;
+  }
+  const d = new Date(ts);
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return `on ${d.getFullYear()}-${mm}-${dd}`;
+}
+
+/** Compact age token for the structured list format: `3d`, `12h`, `now`. */
+export function ageToken(ts: number | undefined, now = Date.now()): string {
+  if (!ts || Number.isNaN(ts)) return "?";
+  const diff = now - ts;
+  if (diff < 60_000) return "now";
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m`;
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h`;
+  if (diff < 60 * 86_400_000) return `${Math.floor(diff / 86_400_000)}d`;
+  const d = new Date(ts);
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return `${d.getFullYear()}-${mm}-${dd}`;
+}
+
+/**
+ * Provenance in the user's words (D68). Used by prose surfaces (HTML
+ * report); the structured list keeps the raw `source=` enum instead.
+ * The distinction that matters to the user is *whose words these were* —
+ * said outright, asked to be saved, auto-captured, or inferred by the
+ * agent and possibly wrong.
+ */
+export function sourceLabel(source: string | undefined): string {
+  switch (source) {
+    case "user":
+      return "you said this";
+    case "cli":
+      return "you saved this from the command line";
+    case "tool":
+      return "you asked me to save this";
+    case "keyword":
+      return "auto-captured from your own wording";
+    case "inference":
+      return "I inferred this — not in your words, check me";
+    case "import":
+      return "imported from another machine";
+    default:
+      return source ? `saved (${source})` : "saved";
+  }
+}
+
+/**
+ * Review state in plain words for project scopes (D68). Personal
+ * memories are always `draft` by design; callers must not show this
+ * for them — "not yet shared" would be alarming noise there.
+ */
+export function reviewStateLabel(reviewState: string | undefined): string {
+  switch (reviewState) {
+    case "draft":
+      return "still in your outbox — not in the repo yet";
+    case "proposed":
+      return "shared with the project, waiting for review";
+    case "approved":
+      return "approved, not yet published";
+    case "published":
+      return "published to the repo";
+    case "rejected":
+      return "reviewed and rejected";
+    default:
+      return reviewState ?? "draft";
+  }
+}
+
+/** Escape user content for HTML. Memory text is arbitrary user input. */
+export function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export interface InventoryHit {
+  id: string;
+  type: string;
+  snippet: string;
+  source?: string;
+  created_at?: number;
+  updated_at?: number;
+  status: string;
+  review_state?: string;
+  scope_key: string;
+}
+
+/**
+ * One structured inventory line (D68):
+ *   3. [fact] id=01K6… created=3d source=user [draft] — body text
+ * Number and id always appear together: the number is for the user's
+ * mouth ("delete #3"), the id is the machine contract. `created=` is
+ * when the memory was learned; `updated=` appears only when it moved
+ * materially later (supersede/promote touch updated_at).
+ *
+ * D70: `index` must be a running counter across every section of one
+ * listing — a per-section counter produces two "#1"s in a single
+ * `scope: both` output, which makes "delete #3" a guess.
+ */
+export function formatInventoryLine(
+  index: number,
+  hit: InventoryHit,
+  personalKey: string,
+  now = Date.now(),
+): string {
+  const parts = [
+    `${index + 1}.`,
+    `[${hit.type}]`,
+    `id=${hit.id}`,
+    `created=${ageToken(hit.created_at ?? hit.updated_at, now)}`,
+    `source=${hit.source || "?"}`,
+  ];
+  const created = hit.created_at ?? hit.updated_at ?? 0;
+  if (hit.updated_at && hit.updated_at - created >= 86_400_000) {
+    parts.push(`updated=${ageToken(hit.updated_at, now)}`);
+  }
+  if (hit.scope_key !== personalKey) {
+    const state = hit.review_state ?? "draft";
+    if (state !== "published") parts.push(`[${state}]`);
+  }
+  if (hit.status !== "active") parts.push(`[${hit.status}]`);
+  const body = hit.snippet.replace(/\s+/g, " ").trim();
+  return `${parts.join(" ")} — ${body}`;
+}
+
+/**
+ * Truncation disclosure (D68): a cut list always says so.
+ * D70: the wording names the surface that can show everything — the CLI —
+ * so a hidden entry is always reachable.
+ */
+export function truncationNote(shown: number, total: number, cli = "open-memex"): string | null {
+  if (total <= shown) return null;
+  return `… and ${total - shown} more not shown (raise limit up to 100, run \`${cli} list --limit 100\`, or use memory_search to find something specific).`;
+}

package/src/retrieve/search.ts

@@ -14,6 +14,9 @@ export interface SearchHit {
   updated_at: number;
   status: string;
   review_state: string;
+  /** D68: provenance + creation time for the plain-language inventory. */
+  source: string;
+  created_at: number;
 }
 
 interface RawRow {
@@ -29,6 +32,8 @@ interface RawRow {
   status: string;
   superseded_by: string | null;
   review_state: string;
+  source?: string;
+  created_at?: number;
 }
 
 function toHit(r: RawRow): SearchHit {
@@ -52,6 +57,8 @@ function toHit(r: RawRow): SearchHit {
     updated_at: r.updated_at,
     status: r.status,
     review_state: r.review_state ?? "draft",
+    source: r.source ?? "",
+    created_at: r.created_at ?? r.updated_at ?? 0,
   };
 }
 
@@ -99,7 +106,7 @@ function resolveVisible(rows: RawRow[], limit: number, stats?: SearchStats): Sea
     const r = db()
       .prepare(
         `SELECT id, scope_key, project_name, type, tags, updated_at, status,
-                superseded_by, review_state, substr(content, 1, 240) AS snippet
+                superseded_by, review_state, source, created_at, substr(content, 1, 240) AS snippet
          FROM memories WHERE id = ?`,
       )
       .get(id) as
@@ -174,7 +181,7 @@ export function search(
 
   const sql = `
     SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.aliases, m.updated_at,
-           m.status, m.superseded_by, m.review_state,
+           m.status, m.superseded_by, m.review_state, m.source, m.created_at,
            snippet(memories_fts, 0, '[', ']', ' ... ', 12) AS snippet,
            bm25(memories_fts) AS score
     FROM memories_fts
@@ -200,6 +207,8 @@ export function search(
     status: string;
     superseded_by: string | null;
     review_state: string;
+    source: string;
+    created_at: number;
     snippet: string;
     score: number;
   }>;
@@ -212,14 +221,14 @@ export function search(
 
 export function list(
   scopeKey: string,
-  opts: { type?: string; limit?: number } = {},
+  opts: { type?: string; limit?: number; include?: "active" | "all" } = {},
 ): SearchHit[] {
   const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));
   const fetchLimit = Math.min(limit * 3 + 10, 150);
   const typeFilter = opts.type ? ` AND type = ?` : "";
   const sql = `
     SELECT id, scope_key, project_name, type, tags, updated_at, status,
-           superseded_by, review_state, substr(content, 1, 240) AS snippet
+           superseded_by, review_state, source, created_at, substr(content, 1, 240) AS snippet
     FROM memories
     WHERE scope_key = ?${typeFilter}
     ORDER BY updated_at DESC
@@ -241,9 +250,45 @@ export function list(
     status: string;
     superseded_by: string | null;
     review_state: string;
+    source: string;
+    created_at: number;
     snippet: string;
   }>;
 
   const raw: RawRow[] = rows.map((r) => ({ ...r, score: 1 }));
+  if (opts.include === "all") {
+    // D68: the audit view — every row as stored (superseded versions,
+    // retracted, archived), no chain collapsing, capped at limit.
+    return raw.slice(0, limit).map(toHit);
+  }
   return resolveVisible(raw, limit);
 }
+
+/**
+ * True totals for the inventory's truncation disclosure (D68). Under
+ * `active` the visible set is the newest of each chain, which in a
+ * consistent store is exactly the rows whose status is active/deprecated.
+ *
+ * D70: one deliberate exception — a `superseded` row whose chain target is
+ * missing (a dangling pointer, which the read path self-heals with a
+ * warning) is returned as a visible hit by resolveVisible but is not
+ * counted here, so the total can read one low in that state. Not worth
+ * widening the query for a self-healing case; the disclosure stays honest
+ * in every state a user can reach deliberately.
+ */
+export function countList(
+  scopeKey: string,
+  opts: { type?: string; include?: "active" | "all" } = {},
+): number {
+  const typeFilter = opts.type ? ` AND type = ?` : "";
+  const statusFilter =
+    opts.include === "all" ? "" : ` AND status IN ('active', 'deprecated')`;
+  const params: unknown[] = [scopeKey];
+  if (opts.type) params.push(opts.type);
+  const row = db()
+    .prepare(
+      `SELECT COUNT(*) AS n FROM memories WHERE scope_key = ?${statusFilter}${typeFilter}`,
+    )
+    .get(...(params as any[])) as { n: number };
+  return row.n;
+}

package/src/scope.ts

@@ -68,6 +68,24 @@ export function resolveCwdScope(worktree: string): Scope {
   return scopeFromSeed(seed, projectName);
 }
 
+/** Pick the directory that seeds scope resolution from a host's candidate
+ *  roots. OpenCode v1 hands the plugin both `worktree` (the repo root — but
+ *  the filesystem root, e.g. `C:\` or `/`, when the opened folder is not a
+ *  git repo) and `directory` (the folder actually opened). Seeding on a
+ *  filesystem root collapses every non-git folder on a drive into one shared
+ *  `project__workspace__…` scope (D71), so prefer `worktree` only when it is
+ *  a real directory below the filesystem root. */
+export function pickScopeRoot(
+  worktree?: string | null,
+  directory?: string | null,
+): string {
+  const isFsRoot = (p: string) => path.parse(p).root === p;
+  if (worktree && !isFsRoot(worktree)) return worktree;
+  if (directory) return directory;
+  if (worktree) return worktree;
+  return process.cwd();
+}
+
 export function resolveProjectScope(worktree: string): Scope {
   const target = worktree && worktree.length > 0 ? worktree : ".";
   const remote = tryGitRemote(target);

package/src/store/lifecycle.ts

@@ -9,6 +9,7 @@ import {
 } from "../paths.ts";
 import { loadConfig } from "../config.ts";
 import { cjkIndexText } from "../retrieve/cjk.ts";
+import { isTurnEcho } from "../capture/handoff.ts";
 import {
   parse,
   serialize,
@@ -67,6 +68,11 @@ export interface DupResult {
 
 export const NEAR_DUP_THRESHOLD = 0.8;
 
+/** `source` values the keyword hook (or an agent marking a user statement) writes.
+ *  Only these are turn-echo candidates — a `tool` memory is the agent's own
+ *  inference and keeps the 0.8 near-dup notice instead of a refusal. */
+const ECHO_SOURCES = "('keyword','user')";
+
 interface IndexRow {
   id: string;
   content_hash: string;
@@ -103,6 +109,52 @@ export function findDuplicates(
   return { exact, near: near.slice(0, 3) };
 }
 
+export interface TurnEchoCandidate extends DuplicateCandidate {
+  source: string;
+}
+
+/**
+ * D73: memories written from the user's own words moments ago — the keyword
+ * hook's captures, plus agent saves marked `source: user`. `memory_add` uses
+ * this to refuse a re-save of a statement the store already holds verbatim
+ * (see TURN_ECHO_THRESHOLD in src/capture/handoff.ts for why the bar is high).
+ * `created_at` is epoch ms in the index, so the window is a numeric compare.
+ */
+export function findTurnEcho(
+  scopeKey: string,
+  body: string,
+  windowMs: number,
+): TurnEchoCandidate[] {
+  const cutoff = Date.now() - windowMs;
+  let rows: Array<{ id: string; content: string; source: string; created_at: number }>;
+  try {
+    rows = db()
+      .prepare(
+        `SELECT id, content, source, created_at FROM memories
+         WHERE scope_key = ? AND status = 'active'
+           AND source IN ${ECHO_SOURCES} AND created_at >= ?`,
+      )
+      .all(scopeKey, cutoff) as typeof rows;
+  } catch {
+    return [];
+  }
+  const out: TurnEchoCandidate[] = [];
+  for (const r of rows) {
+    if (typeof r.created_at !== "number" || r.created_at < cutoff) continue;
+    const score = similarity(body, r.content);
+    if (isTurnEcho(score)) {
+      out.push({
+        id: r.id,
+        score,
+        source: r.source,
+        snippet: r.content.replace(/\s+/g, " ").trim().slice(0, 120),
+      });
+    }
+  }
+  out.sort((x, y) => y.score - x.score);
+  return out.slice(0, 3);
+}
+
 /** Locate a memory file by id: index file_path first, then dir-scan fallback. */
 export function findMemoryFile(id: string): MemoryFile | null {
   const { memories } = paths();

package/src/tools/ops.ts

@@ -7,12 +7,12 @@
  * result; each host adapts that to its own tool-result shape.
  */
 import fs from "node:fs";
-import path from "node:path";
 import { z } from "zod";
 import type { Scope } from "../scope.ts";
 import type { MyOMemoryConfig } from "../config.ts";
 import { PERSONAL_SCOPE } from "../scope.ts";
-import { search, list, hitStateLabel } from "../retrieve/search.ts";
+import { search, list, countList, hitStateLabel } from "../retrieve/search.ts";
+import { formatInventoryLine, truncationNote } from "../retrieve/display.ts";
 import {
   writeMemoryFile,
   readMemoryFile,
@@ -23,12 +23,13 @@ import {
   type Frontmatter,
 } from "../store/markdown.ts";
 import { upsertFromFile, deleteFromIndex } from "../store/sync.ts";
-import { findDuplicates, supersede } from "../store/lifecycle.ts";
+import { findDuplicates, findTurnEcho, supersede, setStatus } from "../store/lifecycle.ts";
+import { TURN_ECHO_WINDOW_MS } from "../capture/handoff.ts";
 import { db } from "../store/db.ts";
 import { redact } from "../redact.ts";
 import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.ts";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.ts";
-import { paths } from "../paths.ts";
+import { isInRepoMemoryFile } from "../paths.ts";
 import {
   proposeMemories,
   promoteMemory,
@@ -65,14 +66,15 @@ export async function withOutboxNote(
 /** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
 export const TOOL_DESCRIPTIONS = {
   memory_add:
-    "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Worth saving: decisions and their reasons, preferences, conventions, gotchas, approaches tried and abandoned. Not worth saving: one-off task details or anything re-derivable from the code. Do not wait to be asked. For facts you infer yourself rather than the user stating, propose them first and save only on approval. Keep each memory to one self-contained statement; attach aliases when the parameter is available. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
+    "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Worth saving: decisions and their reasons, preferences, conventions, gotchas, approaches tried and abandoned. Not worth saving: one-off task details or anything re-derivable from the code. Do not wait to be asked. For facts you infer yourself rather than the user stating, propose them first and save only on approval. Keep each memory to one self-contained statement; attach aliases when the parameter is available. If a note tells you the user's own wording was already stored verbatim this turn, that statement is already saved: do not retry it in a rewording — save only what that text does not contain, or use memory_supersede on the given id. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
   memory_search:
     "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Call before asking the user about past decisions, conventions, or preferences they may have told you before. Search well: break the question into its concepts and try 2–3 phrasings per concept — synonyms, the user's other language, shorter keyword forms — and check the other scope too, before concluding nothing is stored.",
   memory_list:
-    "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
+    "List memories in a scope, newest first, as a numbered inventory. Each line keeps the raw fields — [type] id=… created=… source=… — say them back to the user in plain words (source=user → 'you told me this'; inference → 'I inferred this, check me'; keyword → 'caught from your own wording'), never read the raw id aloud unless they ask. When the user asks 'what do you remember about me?', use scope=both and present the inventory conversationally. The user may point at an entry by its number ('delete #3'): numbers are only valid for the listing you just produced — re-run memory_list, read the candidate back in full, and get a confirmation before calling memory_forget (deletion is permanent). include=all is the audit view (superseded versions, retracted, archived also shown).",
   memory_supersede:
     "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
-  memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
+  memory_forget:
+    "Delete a memory by id. Use when the user asks to forget something. Deletion is permanent: before deleting, restate the memory's content to the user and get a confirmation. With soft=true the memory is hidden instead (retracted: out of lists and search, file kept, one-way).",
   memory_status:
     "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start, when the server reports drafts waiting for review, or when the user says 'sync memory' (or '同步记忆'); then ask the user which drafts to sync. (MCP server and the `open-memex sync-status` CLI; the opencode native plugin does not expose this tool.)",
   memory_submit:
@@ -143,6 +145,12 @@ export const memoryListArgs = {
     ),
   type: z.string().optional(),
   limit: z.number().int().min(1).max(100).optional(),
+  include: z
+    .enum(["active", "all"])
+    .optional()
+    .describe(
+      "D68: `active` (default) shows what is currently remembered — newest version of each fact, retracted/archived hidden. `all` is the audit view: every stored row including superseded versions and hidden ones. The default CHANGED in D68: superseded versions no longer appear unless include=all.",
+    ),
 };
 export type MemoryListArgs = z.infer<z.ZodObject<typeof memoryListArgs>>;
 
@@ -160,6 +168,12 @@ export type MemorySupersedeArgs = z.infer<z.ZodObject<typeof memorySupersedeArgs
 
 export const memoryForgetArgs = {
   id: z.string().min(1),
+  soft: z
+    .boolean()
+    .optional()
+    .describe(
+      "D68: hide instead of delete. The memory is retracted — excluded from lists and search — but its file stays. Retraction is one-way (D64): it does not come back; to restore the fact, save it again as a new memory. Offer `soft` when the user is unsure about deleting.",
+    ),
 };
 export type MemoryForgetArgs = z.infer<z.ZodObject<typeof memoryForgetArgs>>;
 
@@ -281,6 +295,27 @@ export async function addMemory(
       output: `Identical memory already exists: id=${dups.exact.id}. Not duplicated.`,
     };
   }
+  // D73: one user statement, one memory. The keyword hook stores the user's
+  // sentence verbatim with no agent in the loop; a paraphrase of that same
+  // sentence is refused instead of written beside it. The stored id comes back
+  // so the caller can supersede it or save only the genuinely new part.
+  const echo = findTurnEcho(s.key, redacted, TURN_ECHO_WINDOW_MS);
+  if (echo.length > 0) {
+    const top = echo[0];
+    const others = echo
+      .slice(1)
+      .map((e) => `id=${e.id} (${e.source}, overlap ${e.score.toFixed(2)})`)
+      .join(", ");
+    return {
+      title: "memory: already captured verbatim",
+      output:
+        `Not saved — the user's own words were already stored moments ago (source: ${top.source}, overlap ${top.score.toFixed(2)}): ` +
+        `id=${top.id} — ${top.snippet}` +
+        (others ? `\nAlso matching: ${others}` : "") +
+        `\nDo not retry with a rewording: that only adds a second copy of one statement. ` +
+        `Save a separate memory only for information that stored text does not contain, or call memory_supersede on that id if this replaces it.`,
+    };
+  }
   const fm = buildFrontmatter(s, {
     type: args.type ?? "fact",
     tags: args.tags ?? [],
@@ -338,24 +373,37 @@ export async function listMemories(
   getScope: () => Scope,
   args: MemoryListArgs,
 ): Promise<ToolResult> {
+  // D68: the list is the user's inventory of what is remembered. Lines
+  // are structured (number + id + created= + source= + state tags) and
+  // every section reports its true total — a truncated list says so
+  // instead of quietly looking complete (the D66 sync-status lesson).
+  const include = args.include ?? "active";
+  // D70: numbering runs across every section of THIS listing, so "delete
+  // #3" names exactly one memory. A per-section counter emitted two "#1"s.
+  let seq = 0;
+  const render = (scopeKey: string) => {
+    const hits = list(scopeKey, { type: args.type, limit: args.limit, include });
+    const total = countList(scopeKey, { type: args.type, include });
+    const lines = hits.map((h) => formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
+    const note = truncationNote(hits.length, total);
+    if (note) lines.push(note);
+    return lines;
+  };
   if (args.scope === "both") {
     // D64: "what do you remember about me" spans both stores; search
     // already defaults to both, list now matches. Each scope lists its
     // own newest (the limit applies per scope).
     const project = getScope();
     const sections: string[] = [];
-    for (const s of [project, PERSONAL_SCOPE]) {
-      const hits = list(s.key, { type: args.type, limit: args.limit });
-      if (hits.length === 0) {
-        sections.push(`## ${s.kind} (${s.key})\n  (none)`);
-        continue;
-      }
-      const lines = hits.map(
-        (h) => `- [${h.type}]${hitStateLabel(h)} id=${h.id} — ${h.snippet.replace(/\s+/g, " ").trim()}`,
-      );
-      sections.push(`## ${s.kind} (${s.key})\n${lines.join("\n")}`);
+    for (const s of [PERSONAL_SCOPE, project]) {
+      const lines = render(s.key);
+      const heading =
+        s.key === PERSONAL_SCOPE.key
+          ? "## About you (personal — stays on this machine, applies everywhere)"
+          : `## This project (${s.projectName || s.key})`;
+      sections.push(lines.length === 0 ? `${heading}\n(none yet)` : `${heading}\n${lines.join("\n")}`);
     }
-    return { title: "memory: list (both scopes)", output: sections.join("\n") };
+    return { title: "memory: list (both scopes)", output: sections.join("\n\n") };
   }
   const s = resolveScope(
     getScope,
@@ -363,14 +411,18 @@ export async function listMemories(
       ? args.scope
       : undefined,
   );
-  const hits = list(s.key, { type: args.type, limit: args.limit });
-  if (hits.length === 0) {
+  const lines = render(s.key);
+  if (lines.length === 0) {
     return { title: "memory: empty", output: `No memories in scope ${s.key}.` };
   }
-  const lines = hits.map(
-    (h) => `- [${h.type}]${hitStateLabel(h)} id=${h.id} — ${h.snippet.replace(/\s+/g, " ").trim()}`,
-  );
-  return { title: `memory: ${hits.length} in ${s.key}`, output: lines.join("\n") };
+  const heading =
+    s.key === PERSONAL_SCOPE.key
+      ? "## About you (personal — stays on this machine, applies everywhere)"
+      : `## This project (${s.projectName || s.key})`;
+  return {
+    title: `memory: ${countList(s.key, { type: args.type, include })} in ${s.key}`,
+    output: `${heading}\n${lines.join("\n")}`,
+  };
 }
 
 export async function supersedeMemory(
@@ -418,6 +470,28 @@ export async function forgetMemory(args: MemoryForgetArgs): Promise<ToolResult>
   if (!row) {
     return { title: "memory: not found", output: `No memory with id ${args.id}.` };
   }
+  if (args.soft) {
+    // D68: hide instead of delete. The status flip is the whole action —
+    // retrieval and the inventory exclude retracted, the file stays put.
+    // One-way (D64): no un-hide; restoring the fact means saving it again.
+    try {
+      const mf = setStatus(args.id, "retracted");
+      upsertFromFile(mf);
+      return {
+        title: "memory: hidden",
+        output:
+          `Hidden ${args.id} (retracted). It no longer appears in lists or search, but the file is kept. This is one-way — to bring the fact back, save it again as a new memory.` +
+          // D70: a retraction of an in-repo memory is a local working-tree
+          // edit like the delete — without a commit (and a push) the memory
+          // stands on every teammate's clone, so "hidden" would be a lie.
+          (isInRepoMemoryFile(row.file_path)
+            ? ` Note: this memory lives in the repo (.ai/open-memex/), so the retraction is only local until you commit and push it — until then the team still sees it.`
+            : ""),
+      };
+    } catch (e) {
+      return { title: "memory: hide failed", output: (e as Error).message };
+    }
+  }
   // Delete by indexed file_path — location-agnostic (appdata or in-repo, 2B/D24).
   // Only ENOENT counts as "deleted": on any other unlink failure the file
   // is still the source of truth and would be re-indexed on next sync, so
@@ -439,9 +513,7 @@ export async function forgetMemory(args: MemoryForgetArgs): Promise<ToolResult>
   // D64: forgetting an in-repo memory deletes a file inside the user's
   // git working tree. Say so — the deletion should ride a commit, or the
   // file silently diverges from what teammates have.
-  const inRepo =
-    row.file_path.includes(`${path.sep}.ai${path.sep}`) &&
-    !row.file_path.startsWith(paths().root);
+  const inRepo = isInRepoMemoryFile(row.file_path);
   return {
     title: "memory: forgotten",
     output: inRepo