@dzhi/ocpg 0.12.0 → 0.15.0

package/README.md

@@ -3,7 +3,7 @@
 
 Postgres-backed persistent memory plugin for [OpenCode](https://opencode.ai).
 
-Uses the existing `memories` table (`content`, `tags`, `session_id`, `project`, `created_at`, `search_vector`) and the `pg_trgm` extension. Injects recent project memories into the system prompt and exposes `memory_recall` / `memory_remember` / `memory_forget` tools.
+Uses the `memories` table (`content`, `tags`, `session_id`, `project`, `created_at`, `search_vector`, `memory_type`, `access_count`, `last_accessed_at`, `updated_at`) and the `pg_trgm` extension. Injects the memories most relevant to what you're currently asking into the system prompt, captures deliberate "remember that..." prompts verbatim, and exposes `memory_recall` / `memory_remember` / `memory_forget` / `memory_update` tools.
 
 ## Install
 
@@ -21,7 +21,7 @@ In `opencode.json`:
 
 Need a Postgres instance? The [`deploy/`](./deploy) directory ships a hardened Docker Compose setup (localhost-only, `memories` schema auto-created on first boot) - see [`deploy/README.md`](./deploy/README.md).
 
-Configure the connection via environment variables, e.g. in `~/.zshenv`. Any Postgres user and database name will do - use whatever names fit your setup and mirror them here:
+Configure the connection via shell environment variables:
 
 ```bash
 export OCPG_HOST="localhost"
@@ -39,34 +39,34 @@ export OCPG_SSL="disable"
 | `OCPG_USER`     | `ocpguser`   |
 | `OCPG_DB`       | `ocpg`       |
 | `OCPG_SSL`      | `disable`    |
-
-**Password is env-only.** The plugin never reads config files, options, or external secret managers - set `OCPG_PASSWORD` in your shell environment (e.g. via direnv/.envrc, however you source your secrets).
+| `OCPG_INJECTION`| `relevance`  |
 
 `OCPG_SSL` accepts `disable`, `prefer`, `require`, `verify-ca`, or `verify-full` (anything else falls back to `disable`). It defaults to `disable` for the usual localhost setup - **set it to `require` or stricter whenever `OCPG_HOST` is not local**, otherwise the password handshake crosses the network in plaintext.
 
-## Tools
+## How memory works
+
+Memories are **global**: recall, injection, dedup, deletion and updates see and touch every row. The `project` column records which project a memory came from and is shown in output - it is metadata, not a visibility boundary.
 
-- `memory_remember` - store a memory (`content`, `tags`, `force`); rejects near-duplicates within the project
-- `memory_recall` - search past memories (`query`, `tags`, `global`, `limit`)
-- `memory_forget` - delete a memory of the current project by id
+## How injection picks memories
 
-Memories are project-scoped by working directory; use `global: true` on recall to search across projects. `tags` on recall matches rows carrying *all* the given tags — tags aren't covered by full-text search, so this is the only way to reach them.
+By default the block is **relevance-ranked, not recency-ranked**: the user's latest prompt is turned into a full-text query (OR of stemmed words) over **all memories**, ranked by relevance with a small same-project tiebreak, top 5 injected - each line labeled with its origin project. When nothing matches the prompt, it falls back to the latest memories (preferences first). Set `OCPG_INJECTION=recency` for the old blind-last-5 behavior.
 
-Writes are capped at 4000 characters of content, 10 tags, and 64 characters per tag; oversized writes are rejected with the actual size rather than silently truncated.
+This is keyword relevance, not embedding-based semantic search - close phrasing wins, paraphrases may not. Note the OR ranking: common words in a prompt surface more rows; the ranking favors rows matching more distinctive terms.
 
-`memory_forget` only ever deletes within the calling project, so an id from another project matches nothing.
+## Tools
 
-### Duplicate detection
+Four agent tools are registered: `memory_remember` (store), `memory_recall` (search), `memory_forget` (delete by id), `memory_update` (rewrite an existing memory, keeping its original learned date), and `memory_consolidate` (remove near-duplicates on demand). The agent reads their usage rules from the tool schemas - as the user, the things worth knowing are:
 
-`memory_remember` rejects a new memory when the project already holds one with trigram similarity ≥ 0.8, reporting the score and the existing id. Pass `force: true` to store it anyway.
+- Memories are shared across all projects: `memory_forget` / `memory_update` work on any row by id, from any project.
+- Duplicate writes are **never rejected** - they land, the injection block collapses them, and `memory_consolidate` cleans them up when you ask: it keeps the newest of each >=80%-similar group and reports the removed texts so the agent can merge any unique fact back.
 
-This needs the `pg_trgm` extension. Fresh installs from [`deploy/`](./deploy) get it automatically; on an existing database run once:
+Writes are capped at 4000 characters of content, 10 tags, and 64 characters per tag; oversized writes are rejected with the actual size rather than silently truncated. Memories carry a `type` (`preference`, `project_fact` default, or `episodic`); `preference` memories come first in recency mode.
 
-```sql
-CREATE EXTENSION pg_trgm;
-```
+Saying "remember that ..." (or "don't forget ...", "keep in mind ...") in a prompt stores the text after the phrase verbatim, tagged `user-requested` - no model judgment involved.
+
+### Duplicates
 
-Without it, `memory_remember` returns an error naming this exact fix.
+Writes are never rejected for duplicates. Near-duplicates (>=80% content similarity, measured on the real corpus - the old FTS-on-first-60-chars rule missed 28 pairs) are collapsed out of the injected block automatically, and `memory_consolidate` removes them on demand (keeps the newest of each group, reports removed texts for the agent to merge back). Needs the trgm index; fresh installs from [`deploy/`](./deploy) get it automatically, existing databases run the upgrade block in [`deploy/README.md`](./deploy/README.md).
 
 If the database is unreachable, memory injection is skipped and the tools return a generic error - a slow or dead database never blocks a model request.
 

package/ocpg.ts

@@ -13,9 +13,14 @@ type DbConfig = {
   database: string;
   ssl: SslMode;
 };
-type RecallArgs = { query?: string; global?: boolean; limit?: number; tags?: string[] };
-type RememberArgs = { content: string; tags?: string[]; force?: boolean };
+type RecallArgs = { query?: string; limit?: number; tags?: string[] };
+type RememberArgs = {
+  content: string;
+  tags?: string[];
+  type?: MemoryType;
+};
 type ForgetArgs = { id: number };
+type UpdateArgs = { id: number; content: string; tags?: string[]; type?: MemoryType };
 
 // Defaults to "disable" so the common localhost setup is unchanged; set OCPG_SSL
 // when the database is remote, otherwise the SCRAM handshake crosses the network
@@ -64,8 +69,9 @@ export interface MemoryRow {
   date: string;
 }
 
-// The injection query selects neither id nor project - they are never rendered.
-type InjectionRow = Pick<MemoryRow, "content" | "tags" | "date">;
+// Injected lines render each memory's origin project (memories are global),
+// so the injection queries must select project; id is never rendered.
+type InjectionRow = Pick<MemoryRow, "content" | "tags" | "date" | "project">;
 
 // --- Rate-limited error logging ---
 
@@ -125,6 +131,14 @@ async function withDeadline<T>(query: PromiseLike<T>, ms: number): Promise<T> {
 
 // --- Injection pipeline ---
 
+// Injection ranking mode (plan follow-up: relevance over blind recency).
+// "relevance" (default) scores all memories - every project - against the
+// user's latest prompt via full-text search, falling back to recency when the
+// prompt matches nothing; "recency" restores the old last-5 behavior via
+// OCPG_INJECTION=recency. Resolved once at init, env-only.
+let injectionMode: "relevance" | "recency" =
+  process.env.OCPG_INJECTION === "recency" ? "recency" : "relevance";
+
 function truncateMemory(content: string): string {
   if (content.length <= 600) return content;
   return `${content.slice(0, 600)}…[truncated]`;
@@ -137,6 +151,40 @@ function sanitizeMemory(content: string): string {
   return content.replaceAll("</persistent-project-memory>", "");
 }
 
+// Approximates pg_trgm similarity in TS: character-trigram Jaccard. Used only
+// to collapse near-duplicate rows out of the injection candidates (the
+// candidate set is tiny), never for storage decisions.
+function trigrams(text: string): Set<string> {
+  const s = text.toLowerCase().replace(/\s+/g, " ");
+  const out = new Set<string>();
+  for (let i = 0; i < s.length - 2; i++) out.add(s.slice(i, i + 3));
+  return out;
+}
+
+function nearDupe(a: string, b: string): boolean {
+  return nearDupeSets(trigrams(a), trigrams(b));
+}
+
+function nearDupeSets(A: Set<string>, B: Set<string>): boolean {
+  if (A.size === 0 || B.size === 0) return false;
+  let inter = 0;
+  for (const t of A) if (B.has(t)) inter++;
+  return inter / (A.size + B.size - inter) >= DEDUP_SIMILARITY;
+}
+
+// Injection fetches a deeper candidate slice (rank-ordered) and greedily drops
+// rows that near-dupe an already-kept row, emitting the top 5. Without this,
+// duplicate writes (there is no write-time rejection) would fill the 5 slots
+// with restatements of one fact.
+function collapseDupes(rows: InjectionRow[]): InjectionRow[] {
+  const kept: InjectionRow[] = [];
+  for (const row of rows) {
+    if (kept.length >= 5) break;
+    if (!kept.some((k) => nearDupe(k.content, row.content))) kept.push(row);
+  }
+  return kept;
+}
+
 function formatBlock(rows: InjectionRow[], projectDir: string): string {
   if (rows.length === 0) return "";
   const lines: string[] = [
@@ -147,7 +195,10 @@ function formatBlock(rows: InjectionRow[], projectDir: string): string {
   for (const row of rows) {
     const tags = row.tags ?? [];
     const tagStr = tags.length ? ` [${tags.join(", ")}]` : "";
-    lines.push(`- [${row.date}]${tagStr} ${sanitizeMemory(truncateMemory(row.content))}`);
+    // Origin project matters now that memories are shared: basename keeps the
+    // injected line short.
+    const origin = row.project.split('/').pop() ?? row.project;
+    lines.push(`- [${row.date}] (${origin})${tagStr} ${sanitizeMemory(truncateMemory(row.content))}`);
   }
   lines.push("");
   lines.push(
@@ -157,43 +208,122 @@ function formatBlock(rows: InjectionRow[], projectDir: string): string {
   return lines.join("\n");
 }
 
-// Keyed by project directory, not session: the query depends only on the
-// directory, so every session in a project shares one entry and a remember in
-// any session invalidates it for all of them. An empty string is cached for
-// projects with no memories so they stop re-querying, and nothing is injected.
+// Keyed by directory + prompt hash now that the block depends on the prompt
+// (relevance mode): an identical prompt (model retries, re-requests) hits the
+// cache; a new prompt queries afresh. An empty string is cached for
+// no-match/empty prompts so they stop re-querying.
 const injectionCache = new Map<string, string>();
 
-// Session-independent by design: the block depends only on the project
-// directory, so the hook passes nothing else.
+// djb2 - just a stable key shortener; a same-hash different-prompt collision
+// would serve a stale block, which remember/forget invalidation clears.
+function hashQuery(text: string): string {
+  let h = 5381;
+  for (let i = 0; i < text.length; i++) h = ((h << 5) + h + text.charCodeAt(i)) | 0;
+  return (h >>> 0).toString(36);
+}
+
+// The latest user message is the retrieval signal: what the user is asking
+// about right now is the best proxy for which memories matter. Text parts
+// only; capped because a query is a query, not a transcript - FTS is not
+// helped by thousands of characters.
+function extractPromptQuery(
+  messages: ReadonlyArray<{ role: unknown; content: ReadonlyArray<{ type?: unknown; text?: unknown }> }>,
+): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "user") continue;
+    const text = message.content
+      .filter((p) => p.type === "text" && typeof p.text === "string")
+      .map((p) => p.text as string)
+      .join(" ")
+      .trim();
+    return text.length > 512 ? text.slice(0, 512) : text;
+  }
+  return "";
+}
+
+// Recency query shared by the recency mode and the no-match fallback: latest 5
+// rows across ALL memories, preferences first. Global by design - the project
+// column records origin, not visibility.
+// Query builders are pure functions of the client so the benchmark
+// (bench/run.ts) can execute the EXACT production SQL against bench
+// databases - no drift between what is measured and what runs.
+function buildRecencyQuery(client: SQL) {
+  // LIMIT 20: a candidate slice for collapseDupes, not the final block.
+  return client`
+    SELECT content, coalesce(tags, '{}') AS tags,
+           to_char(created_at, 'YYYY-MM-DD') AS date,
+           project
+    FROM memories
+    ORDER BY (memory_type = 'preference') DESC, created_at DESC
+    LIMIT 20
+  `;
+}
+
+function buildRelevanceQuery(client: SQL, tsQuery: string, directory: string) {
+  // Relevance: full-text search across ALL memories - global by design - with
+  // a small same-project boost to break rank ties toward locally stored
+  // memories.
+  return client`
+    SELECT content, coalesce(tags, '{}') AS tags,
+           to_char(created_at, 'YYYY-MM-DD') AS date,
+           project
+    FROM memories
+    WHERE search_vector @@ to_tsquery('english', ${tsQuery})
+    ORDER BY ts_rank(search_vector, to_tsquery('english', ${tsQuery}))
+             + (CASE WHEN project = ${directory} THEN 0.01 ELSE 0 END) DESC,
+             created_at DESC
+    LIMIT 20
+  `;
+}
+
+// The prompt as an OR of stemmed words: websearch_to_tsquery ANDs the terms,
+// so one word the memory never uses would zero out the whole query (bench:
+// recall 0.00-0.02 on multi-word queries). OR ranks by how many (and how
+// rare) the matched terms are, and sanitizing to [a-z0-9]+ tokens keeps
+// to_tsquery syntax-safe. Capped at 24 words to bound the query.
+function orTsQuery(text: string): string {
+  const words = text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+  return words.slice(0, 24).join(" | ");
+}
+
+// The block depends on the directory plus (in relevance mode) the prompt,
+// passed explicitly by the caller.
 async function handleTransform(
   output: { system: string[] },
   directory: string,
+  prompt = "",
 ): Promise<void> {
   if (!directory) return;
-  const cached = injectionCache.get(directory);
+  const query = injectionMode === "relevance" ? prompt.trim() : "";
+  const cacheKey = `${directory}\u0001${hashQuery(query)}`;
+  const cached = injectionCache.get(cacheKey);
   if (cached !== undefined) {
     if (cached) output.system.push(cached);
     return;
   }
   try {
-    const rows = await withDeadline(
-      sql`
-      SELECT content, coalesce(tags, '{}') AS tags,
-             to_char(created_at, 'YYYY-MM-DD') AS date
-      FROM memories
-      WHERE project = ${directory}
-      ORDER BY created_at DESC
-      LIMIT 5
-    ` as unknown as PromiseLike<InjectionRow[]>,
-      1000,
-    );
-    const block = formatBlock(rows, directory);
+    let rows: InjectionRow[];
+    const tsQuery = orTsQuery(query);
+    if (tsQuery) {
+      rows = await withDeadline(
+        buildRelevanceQuery(sql, tsQuery, directory) as unknown as PromiseLike<InjectionRow[]>,
+        1000,
+      );
+      if (rows.length === 0) {
+        // No keyword match for this prompt - recency beats an empty block.
+        rows = await withDeadline(buildRecencyQuery(sql) as unknown as PromiseLike<InjectionRow[]>, 1000);
+      }
+    } else {
+      rows = await withDeadline(buildRecencyQuery(sql) as unknown as PromiseLike<InjectionRow[]>, 1000);
+    }
+    const block = formatBlock(collapseDupes(rows), directory);
     // Evict oldest entry when cache exceeds 32
     if (injectionCache.size >= 32) {
       const firstKey = injectionCache.keys().next().value;
       if (firstKey !== undefined) injectionCache.delete(firstKey);
     }
-    injectionCache.set(directory, block);
+    injectionCache.set(cacheKey, block);
     if (block) output.system.push(block);
   } catch (e: unknown) {
     logError("inject", `ocpg injection failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -229,6 +359,19 @@ const MIN_CONTENT = 10;
 const MAX_TAGS = 10;
 const MAX_TAG_LENGTH = 64;
 
+// --- Memory types (plan 2.1: defaulted, never required) ---
+
+// The stored vocabulary mirrors the DB CHECK constraint (memories_type_check);
+// rows predate the column, so "required" would break every existing caller -
+// type is always defaulted. episodic is reserved for the (cut, opt-in) 1.3
+// feature; remember accepts it so the vocabulary stays in one place.
+const MEMORY_TYPES = ["preference", "project_fact", "episodic"] as const;
+type MemoryType = (typeof MEMORY_TYPES)[number];
+
+function resolveMemoryType(raw: unknown): MemoryType {
+  return MEMORY_TYPES.includes(raw as MemoryType) ? (raw as MemoryType) : "project_fact";
+}
+
 // Raw JSON Schema input is not coerced for us: a model sending "3" or null for
 // limit would otherwise reach Postgres as LIMIT NaN.
 function resolveLimit(raw: unknown): number {
@@ -253,15 +396,13 @@ function toolError(kind: string, action: string, e: unknown): string {
 
 async function recall(
   args: RecallArgs,
-  ctx: { directory: string },
 ): Promise<string> {
   try {
     const limit = resolveLimit(args.limit);
-    const projectCond = args.global
-      ? sql``
-      : sql`AND project = ${ctx.directory}`;
+    // All memories are global: no project filter anywhere - the project column
+    // records origin (shown in output), not visibility.
     const queryCond = args.query
-      ? sql`AND search_vector @@ websearch_to_tsquery('english', ${args.query})`
+      ? sql`AND search_vector @@ to_tsquery('english', ${orTsQuery(args.query)})`
       : sql``;
     // Tags are not part of search_vector (it covers content only), so they are
     // unreachable by query alone. Matches rows carrying ALL the given tags,
@@ -270,20 +411,34 @@ async function recall(
     const tagCond = tagList.length
       ? sql`AND tags @> ${sql.array(tagList, "text")}`
       : sql``;
-    // Relevance-ranked when searching; recency-ordered for a plain project browse.
+    // Relevance-ranked when searching; undirected browse is plain recency
+    // (preferences first, matching the injection fallback). A frequency blend
+    // was tried and removed: bumping exactly the returned top-5 is a
+    // rich-get-richer loop - live corpus rows pinned the top slot after a few
+    // runs. access_count stays as data collection; no ranking consumes it.
     const orderBy = args.query
-      ? sql`ORDER BY ts_rank(search_vector, websearch_to_tsquery('english', ${args.query})) DESC`
-      : sql`ORDER BY created_at DESC`;
+      ? sql`ORDER BY ts_rank(search_vector, to_tsquery('english', ${orTsQuery(args.query)})) DESC`
+      : sql`ORDER BY (memory_type = 'preference') DESC, created_at DESC`;
 
     const rows = await sql`
       SELECT id, content, coalesce(tags, '{}') AS tags,
              to_char(created_at, 'YYYY-MM-DD') AS date,
-             project
+             project, memory_type
       FROM memories
-      WHERE 1=1 ${projectCond} ${queryCond} ${tagCond}
+      WHERE 1=1 ${queryCond} ${tagCond}
       ${orderBy}
       LIMIT ${limit}
-    ` as MemoryRow[];
+    ` as (MemoryRow & { memory_type: string })[];
+
+    // Access ranking is recall-only (plan 2.2): the injection path stays
+    // read-only because its per-directory cache would make increments biased.
+    // Fire-and-forget so the UPDATE never sits on the read path's latency.
+    const ids = rows.map((r) => r.id);
+    if (ids.length > 0) {
+      void sql`UPDATE memories SET access_count = access_count + 1, last_accessed_at = now() WHERE id = ANY(${sql.array(ids, "int8")})`.catch(
+        (e: unknown) => logError("access", `ocpg access bump failed: ${e instanceof Error ? e.message : String(e)}`),
+      );
+    }
 
     if (rows.length === 0) return "No memories found.";
 
@@ -291,7 +446,10 @@ async function recall(
       .map((r) => {
         const tags = r.tags ?? [];
         const tagStr = tags.length ? ` (${tags.join(', ')})` : '';
-        return `[${r.date}] [${r.project}]${tagStr}\n#${r.id}\n${r.content}`;
+        // preference/episodic are worth surfacing; project_fact is the default
+        // every pre-column row carries, so printing it is pure noise.
+        const typeStr = r.memory_type === "project_fact" ? "" : ` [${r.memory_type}]`;
+        return `[${r.date}] [${r.project}]${typeStr}${tagStr}\n#${r.id}\n${r.content}`;
       })
       .join('\n---\n');
   } catch (e: unknown) {
@@ -318,14 +476,17 @@ function validateWrite(args: RememberArgs): string | null {
   if (oversized !== undefined) {
     return `ERROR: each tag must be a string of at most ${MAX_TAG_LENGTH} characters.`;
   }
+  if (args.type !== undefined && !MEMORY_TYPES.includes(args.type)) {
+    return `ERROR: type must be one of ${MEMORY_TYPES.join(", ")}.`;
+  }
   return null;
 }
 
-// Trigram similarity threshold for dedup-on-write. Measured on a real
-// 485-memory corpus: the previous rule (FTS on the first 60 characters) let 28
-// pairs at >=0.8 similarity through because they differed in their opening
-// words, while wrongly rejecting ~1% of genuinely distinct memories. 0.8 is
-// strict enough that only restatements collide.
+// Trigram similarity threshold for near-duplicate handling (consolidation and
+// the injection collapse pass). Measured on a real 485-memory corpus: 0.8 is
+// strict enough that only restatements collide. Writes never reject on it -
+// duplicates are cleaned up by memory_consolidate and collapsed out of the
+// injected block.
 const DEDUP_SIMILARITY = 0.8;
 
 async function remember(
@@ -336,45 +497,74 @@ async function remember(
     const invalid = validateWrite(args);
     if (invalid) return invalid;
 
-    // Tags are stored verbatim - project scoping lives in the project column, not tags.
+    // Tags are stored verbatim - the project column records origin, not visibility.
     const tags = args.tags ?? [];
     const basename = ctx.directory.split('/').pop() ?? ctx.directory;
 
-    if (!args.force) {
-      // Dedup: project-scoped trigram similarity over the whole content. No
-      // trigram index - the project filter narrows to a few hundred rows, which
-      // similarity() scans in single-digit milliseconds.
-      const dedup = await sql`
-        SELECT id, round(similarity(content, ${args.content})::numeric, 2) AS score
-        FROM memories
-        WHERE project = ${ctx.directory}
-          AND (content = ${args.content} OR similarity(content, ${args.content}) >= ${DEDUP_SIMILARITY})
-        ORDER BY similarity(content, ${args.content}) DESC
-        LIMIT 1
-      ` as { id: number; score: string }[];
-
-      if (dedup.length > 0) {
-        return `Similar memory already stored as #${dedup[0].id} (similarity ${dedup[0].score}) for this project; skipping insert. Pass force: true to store it anyway.`;
-      }
-    }
-
     // sql.array(tags) alone encodes text[] with quoted elements under bun 1.4.2;
     // the element type hint is required for clean array storage.
     const inserted = await sql`
-      INSERT INTO memories (content, tags, session_id, project)
-      VALUES (${args.content}, ${sql.array(tags, "text")}, ${ctx.sessionID}, ${ctx.directory})
+      INSERT INTO memories (content, tags, session_id, project, memory_type)
+      VALUES (${args.content}, ${sql.array(tags, "text")}, ${ctx.sessionID}, ${ctx.directory}, ${resolveMemoryType(args.type)})
       RETURNING id
     ` as { id: number }[];
 
+    // The injection block is global, but its cache is keyed by the calling
+    // directory + prompt; clear the directory's keys.
     invalidateInjection(ctx.directory);
-    return `Stored memory #${inserted[0].id} for project ${basename}.`;
+    return `Stored memory #${inserted[0].id} (project ${basename}).`;
   } catch (e: unknown) {
     return toolError("remember", "remember", e);
   }
 }
 
-// Project-scoped by construction: an agent can only delete what its own project
-// can recall, so a poisoned id from another project silently matches nothing.
+// --- Keyword capture (plan 1.1, revised) ---
+
+// Deterministic capture, no LLM: a trigger phrase in the prompt stores the text
+// following it verbatim (minus the trigger) through the normal write path.
+// Extracting "relevant content" instead would be a model judgment on the
+// prompt-admission path - nondeterministic, and it violates the project rule
+// that model judgment never becomes load-bearing (memory #1555).
+const MEMORY_TRIGGER_RE =
+  /\b(?:remember(?:\s+(?:this|that|to))?|do(?:n'?| no)t forget(?:\s+(?:this|that|to))?|keep (?:this|that )?in mind(?: that)?)\b\s*[:,]?\s*/i;
+
+// Interrogative follow-ons are questions about the past ("remember when the
+// pool broke?"), not storage requests. The list is deliberately narrow:
+// "remember that when X happens, do Y" is imperative and must be captured, so
+// "when" alone is not enough - only skip the bare question forms.
+const INTERROGATIVE_RE = /^(?:when|what|where|why|how|who|whom|whose|which|did)\b/i;
+
+function extractMemoryRequest(text: string): string | null {
+  const match = MEMORY_TRIGGER_RE.exec(text);
+  if (!match) return null;
+  const rest = text.slice(match.index + match[0].length).trim();
+  if (!rest || INTERROGATIVE_RE.test(rest)) return null;
+  return rest;
+}
+
+// Fire-and-forget by design: prompt admission must not wait on a database
+// write, and the prompt itself is never mutated on failure.
+//
+// Not exactly-once: the docs allow prompt hooks to run more than once under
+// concurrent submissions. Dedup-on-write (trigram similarity) is the guard -
+// no hook-side deduplication layer on top of it.
+async function captureFromPrompt(
+  text: string,
+  directory: string,
+  sessionID: string,
+): Promise<void> {
+  const content = extractMemoryRequest(text);
+  if (!content) return;
+  try {
+    await remember({ content, tags: ["user-requested"] }, { directory, sessionID });
+  } catch (e: unknown) {
+    logError("capture", `ocpg keyword capture failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+// Memories are global: any project can delete any row by id - recall shows
+// ids across projects, so deletability matches visibility. The project column
+// stays as origin metadata, not an authorization boundary.
 async function forget(
   args: ForgetArgs,
   ctx: { directory: string },
@@ -386,12 +576,12 @@ async function forget(
     }
     const deleted = await sql`
       DELETE FROM memories
-      WHERE id = ${id} AND project = ${ctx.directory}
+      WHERE id = ${id}
       RETURNING id
     ` as { id: number }[];
 
     if (deleted.length === 0) {
-      return `No memory #${id} in this project; nothing deleted.`;
+      return `No memory #${id}; nothing deleted.`;
     }
     invalidateInjection(ctx.directory);
     return `Deleted memory #${id}.`;
@@ -400,8 +590,126 @@ async function forget(
   }
 }
 
+// No dedup fall-through, by design: an update that lands close to another
+// memory is an intentional correction, not a dupe to reject. updated_at is
+// set; created_at is deliberately NOT bumped - the displayed date must keep
+// saying when the memory was learned, not when it was last edited. Omitted
+// tags/type are preserved, not reset to their defaults.
+async function updateMemory(
+  args: UpdateArgs,
+  ctx: { directory: string },
+): Promise<string> {
+  try {
+    const id = Number(args.id);
+    if (!Number.isInteger(id) || id <= 0) {
+      return "ERROR: id must be a positive integer (the #id shown by memory_recall).";
+    }
+    const invalid = validateWrite(args);
+    if (invalid) return invalid;
+
+    const tags = args.tags ?? [];
+    const tagCond = Array.isArray(args.tags)
+      ? sql`tags = ${sql.array(tags, "text")},`
+      : sql``;
+    const typeCond = args.type !== undefined
+      ? sql`memory_type = ${resolveMemoryType(args.type)},`
+      : sql``;
+    const updated = await sql`
+      UPDATE memories
+      SET content = ${args.content},
+          ${tagCond}
+          ${typeCond}
+          updated_at = now()
+      WHERE id = ${id}
+      RETURNING id
+    ` as { id: number }[];
+
+    if (updated.length === 0) {
+      return `No memory #${id}; nothing updated.`;
+    }
+    invalidateInjection(ctx.directory);
+    return `Updated memory #${id}.`;
+  } catch (e: unknown) {
+    return toolError("update", "update", e);
+  }
+}
+
+// Deterministic consolidation, no model calls inside the plugin: find
+// near-duplicate clusters (trigram similarity >= DEDUP_SIMILARITY over the
+// whole content, global), keep the newest of each, delete the rest. The
+// deleted texts are returned verbatim so the CALLING agent - itself a model -
+// can merge any unique fact back into the survivor via memory_update. Merging
+// is language synthesis, which is the caller's job, not the plugin's.
+// Runs on demand (user-invoked), never on a schedule; capped at 25 clusters
+// per run so a wildly-duplicated corpus cannot turn into one huge report.
+async function consolidate(): Promise<string> {
+  try {
+    const rows = await sql`
+      SELECT id, content, coalesce(tags, '{}') AS tags, created_at
+      FROM memories
+      ORDER BY created_at DESC
+    ` as { id: number; content: string; tags: string[]; created_at: Date }[];
+
+    // Greedy clustering newest-first: each row joins the first cluster whose
+    // representative (the newest member) it near-dupes. Trigram sets are built
+    // once (rebuilding per comparison made consolidate O(n^2) set-constructions,
+    // seconds at 5k rows), and a size-ratio prefilter skips pairs whose Jaccard
+    // can never reach the threshold.
+    type Entry = { row: (typeof rows)[number]; set: Set<string> };
+    const entries: Entry[] = rows.map((row) => ({ row, set: trigrams(row.content) }));
+    const clusters: Array<Array<Entry>> = [];
+    for (const entry of entries) {
+      const host = clusters.find((c) => {
+        const ra = c[0].set.size;
+        const rb = entry.set.size;
+        // Jaccard >= 0.8 is impossible when one set is much smaller; the
+        // comparison itself is the expensive part, so prefilter on sizes.
+        if (ra === 0 || rb === 0 || ra > rb * 4 || rb > ra * 4) return false;
+        return nearDupeSets(c[0].set, entry.set);
+      });
+      if (host) host.push(entry);
+      else clusters.push([entry]);
+    }
+
+    const multi = clusters.filter((c) => c.length > 1).slice(0, 25);
+    if (multi.length === 0) return "No duplicates found; nothing to consolidate.";
+
+    let removed = 0;
+    const report: string[] = [];
+    for (const cluster of multi) {
+      const survivor = cluster[0].row;
+      const removedRows = cluster.slice(1).map((e) => e.row);
+      for (const r of removedRows) {
+        await sql`DELETE FROM memories WHERE id = ${r.id}`;
+      }
+      removed += removedRows.length;
+      // Show what died so the calling agent can merge unique facts back into
+      // the survivor.
+      report.push(
+        `Kept #${survivor.id}: ${truncateMemory(survivor.content)}\n` +
+          removedRows.map((r) => `  removed #${r.id}: ${truncateMemory(r.content)}`).join("\n"),
+      );
+    }
+
+    if (removed > 0) injectionCache.clear();
+    return (
+      `Removed ${removed} duplicate ${removed === 1 ? "memory" : "memories"} across ${multi.length} groups (kept the newest of each).\n` +
+      `Check the removed texts - if any carries a fact the kept memory lacks, merge it in with memory_update:\n\n` +
+      report.join("\n")
+    );
+  } catch (e: unknown) {
+    return toolError("consolidate", "consolidate", e);
+  }
+}
+
+// Clears every cache entry for the directory - relevance mode keys by
+// directory + prompt hash, so a write invalidates them all.
 function invalidateInjection(directory: string): void {
-  injectionCache.delete(directory);
+  for (const key of [...injectionCache.keys()]) {
+    if (key === directory || key.startsWith(`${directory}\u0001`)) {
+      injectionCache.delete(key);
+    }
+  }
 }
 
 // V2 entrypoint: registers the system-context injection hook and the agent tools
@@ -419,20 +727,33 @@ const ocpg = Plugin.define({
     void sql`SELECT 1`.catch(() => {});
 
     // Inject project memories into every model request's system context.
-    // handleTransform owns the per-directory cache (32-slot, invalidated on remember).
+    // Relevance mode derives the retrieval query from the latest user message;
+    // handleTransform owns the cache (32-slot, keyed by directory + prompt).
     await ctx.session.hook("context", async (event) => {
       const output: { system: string[] } = { system: [] };
-      await handleTransform(output, directory);
+      await handleTransform(output, directory, extractPromptQuery(event.messages));
       for (const text of output.system) event.system.push({ type: "text", text });
     });
 
+    // Keyword capture (plan 1.1 revised): a trigger phrase ("remember this,
+    // ...") stores the following text verbatim through the normal write path -
+    // same validateWrite, same trigram dedup. No LLM call, and the prompt
+    // itself is never mutated.
+    await ctx.session.hook("prompt", (event) => {
+      void captureFromPrompt(event.prompt.text, directory, event.sessionID);
+    });
+
     // Agent tools: recall + remember with dedup-on-write. Input schemas are raw
     // JSON Schema (V2 contract); sizes are enforced in remember().
     await ctx.tool.transform((editor) => {
       editor.add({
         name: "memory_recall",
+        // Direct (non-codemode) tool: memory ops are single-shot calls, not
+        // scriptable sequences - hiding them behind the execute sandbox only
+        // breaks direct invocation without adding value.
+        options: { codemode: false },
         description:
-          "Search past memories stored for this project. Use before non-trivial work to check for relevant lessons, fixes, and decisions.",
+          "Search past memories across all projects. Use before non-trivial work to check for relevant lessons, fixes, and decisions.",
         input: {
           type: "object",
           properties: {
@@ -440,25 +761,27 @@ const ocpg = Plugin.define({
             tags: {
               type: "array",
               items: { type: "string" },
-              description: "Only return memories carrying all of these tags",
+              description:
+                "Only return memories carrying all of these tags. Tags are not full-text " +
+                "searchable (search covers content only), so this filter is the only way to reach them.",
             },
-            global: { type: "boolean", description: "Search across all projects (default: current project only)" },
             limit: { type: "number", description: "1-20, default 5" },
           },
           additionalProperties: false,
         },
         execute: async (input) => {
-          return { content: await recall(input as RecallArgs, { directory }) };
+          return { content: await recall(input as RecallArgs) };
         },
       });
       editor.add({
         name: "memory_remember",
+        options: { codemode: false },
         // This description is the only place the write policy is guaranteed to
         // reach the model: it is in the tool schema every session, whereas the
         // injected block is skipped entirely for projects with no memories and
         // the user may have no project instructions at all.
         description:
-          "Store a durable memory for this project. Use after user corrections (immediately), " +
+          "Store a durable memory shared across all projects. Use after user corrections (immediately), " +
           "architecture decisions, non-trivial fixes, environment facts, and stated preferences. " +
           "Do not store session progress, secrets, or anything the code itself already states.",
         input: {
@@ -468,19 +791,21 @@ const ocpg = Plugin.define({
               type: "string",
               description: `1-3 self-contained sentences capturing the why (${MIN_CONTENT}-${MAX_CONTENT} characters)`,
             },
+            type: {
+              type: "string",
+              enum: [...MEMORY_TYPES],
+              description:
+                "preference = a standing user preference (these are injected first); " +
+                "project_fact (default) = decisions, fixes, env facts. Omit unless the memory is a preference.",
+            },
             tags: {
               type: "array",
               items: { type: "string", maxLength: MAX_TAG_LENGTH },
               maxItems: MAX_TAGS,
               description:
-                "Category prefixes: preference, decision, debug, env, architecture, workaround, " +
-                "language:<x>, framework:<x>, tool:<x>. Project scoping is automatic (a project " +
-                "column, not a tag) - never add project:<name>.",
-            },
-            force: {
-              type: "boolean",
-              description:
-                "Store even if a similar memory exists (use only after a dedup rejection you judge to be wrong)",
+                "Fine-grained facets: decision, debug, env, architecture, workaround, " +
+                "language:<x>, framework:<x>, tool:<x>. The origin project is recorded " +
+                "automatically (a project column, not a tag) - never add project:<name>.",
             },
           },
           required: ["content"],
@@ -492,8 +817,10 @@ const ocpg = Plugin.define({
       });
       editor.add({
         name: "memory_forget",
+        options: { codemode: false },
         description:
-          "Delete a memory of this project by id (get ids from memory_recall). Use for memories that are wrong or obsolete; prefer storing a corrected memory when the old one is still useful history.",
+          "Delete a memory by id (get ids from memory_recall). Use for memories that are wrong or obsolete; prefer storing a corrected memory when the old one is still useful history. " +
+          "Memories are shared across projects, so any project can delete any of them.",
         input: {
           type: "object",
           properties: {
@@ -506,6 +833,60 @@ const ocpg = Plugin.define({
           return { content: await forget(input as ForgetArgs, { directory }) };
         },
       });
+      editor.add({
+        name: "memory_update",
+        options: { codemode: false },
+        description:
+          "Rewrite an existing memory by id (get ids from memory_recall). Use when a memory is outdated but still worth keeping: the corrected content replaces the old, keeping the original learned date. " +
+          "Omitted tags/type are kept as-is. For obsolete memories use memory_forget; for genuinely new memories use memory_remember.",
+        input: {
+          type: "object",
+          properties: {
+            id: { type: "number", description: "The #id shown by memory_recall" },
+            content: {
+              type: "string",
+              description: `1-3 self-contained sentences replacing the old content (${MIN_CONTENT}-${MAX_CONTENT} characters)`,
+            },
+            tags: {
+              type: "array",
+              items: { type: "string", maxLength: MAX_TAG_LENGTH },
+              maxItems: MAX_TAGS,
+              description: "Replaces the tag list; omit to keep the current tags",
+            },
+            type: {
+              type: "string",
+              enum: [...MEMORY_TYPES],
+              description: "Replaces the memory type; omit to keep the current type",
+            },
+          },
+          required: ["id", "content"],
+          additionalProperties: false,
+        },
+        execute: async (input) => {
+          return { content: await updateMemory(input as UpdateArgs, { directory }) };
+        },
+      });
+      editor.add({
+        name: "memory_consolidate",
+        options: { codemode: false },
+        // User-invoked cleanup, not a write-path gate: writes never reject on
+        // duplicates, so call this when the corpus has accumulated near-dupes.
+        // User-invoked cleanup, not a write-path gate: writes never reject on
+        // duplicates, so call this when the corpus has accumulated near-dupes.
+        // The deleted texts come back in the result so the calling agent can
+        // merge unique facts into the survivors via memory_update.
+        description:
+          "Remove near-duplicate memories: keeps the newest of each >=80%-similar content group anywhere in the store and deletes the rest, returning the removed texts. " +
+          "After running it, merge any unique fact from the removed texts into the kept memory via memory_update. Deterministic - run it when the user asks to tidy or consolidate memories.",
+        input: {
+          type: "object",
+          properties: {},
+          additionalProperties: false,
+        },
+        execute: async () => {
+          return { content: await consolidate() };
+        },
+      });
     });
 
     // Close the SQL pool when the last plugin instance unloads.
@@ -525,14 +906,29 @@ const __internals = {
   recall,
   remember,
   forget,
+  updateMemory,
+  consolidate,
+  extractMemoryRequest,  captureFromPrompt,
   invalidateInjection,
   resolveSslMode,
   resolveLimit,
+  resolveMemoryType,
   validateWrite,
   logError,
   toolError,
   rateLimitOk,
   resetRateLimit,
+  get injectionMode() {
+    return injectionMode;
+  },
+  setInjectionMode(mode: "relevance" | "recency") {
+    injectionMode = mode;
+  },
+  extractPromptQuery,
+  hashQuery,
+  orTsQuery,
+  buildRecencyQuery,
+  buildRelevanceQuery,
   retain,
   dispose,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhi/ocpg",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "Postgres-backed persistent memory plugin for OpenCode",
   "main": "ocpg.ts",
@@ -8,7 +8,9 @@
     "check": "biome check .",
     "format": "biome format --write .",
     "typecheck": "tsc --noEmit",
-    "test": "bun test"
+    "test": "bun test",
+    "bench:generate": "bun bench/generate.ts",
+    "bench": "bun bench/run.ts"
   },
   "exports": {
     ".": "./ocpg.ts"