@pcircle/memesh 4.5.1 → 4.6.1

package/scripts/hooks/session-summary.js

@@ -24,12 +24,12 @@ import { createRequire } from 'module';
 import { basename, join } from 'path';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'fs';
 import { spawn } from 'child_process';
-import os from 'os';
 import { pathToFileURL } from 'url';
 import {
   AUTO_CAPTURE_TAG,
   captureEntity,
   decideAutoUpdateHook,
+  extractCitedMemoryIds,
   getMemeshDirFromDbPath,
   getProjectName,
   importFromPluginRoot,
@@ -41,6 +41,7 @@ import {
   resolveAutoUpdatePolicy,
   resolvePluginRoot,
   spawnAutoUpdate,
+  truncateTitle,
 } from './_shared.js';
 
 const require = createRequire(import.meta.url);
@@ -90,9 +91,15 @@ function parseTranscript(transcriptPath) {
   const errorsEncountered = [];
   let toolCallCount = 0;
   let readFailed = false;
+  // The raw file content, returned so downstream consumers (the
+  // recall-effectiveness block) reuse this single read instead of a second
+  // readFileSync — real transcripts reach 47MB, so a second full read plus
+  // re-parse doubles the Stop hook's dominant I/O cost.
+  let rawText = '';
 
   try {
-    const lines = readFileSync(transcriptPath, 'utf8').split('\n').filter(l => l.trim());
+    rawText = readFileSync(transcriptPath, 'utf8');
+    const lines = rawText.split('\n').filter(l => l.trim());
     for (const line of lines) {
       try {
         const entry = JSON.parse(line);
@@ -171,7 +178,7 @@ function parseTranscript(transcriptPath) {
     }
   }
 
-  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount, readFailed };
+  return { filesEdited: [...filesEdited], bashCommands, errorsEncountered, toolCallCount, readFailed, rawText };
 }
 
 // Main: read stdin, extract insights, store in DB
@@ -268,8 +275,9 @@ process.stdin.on('end', async () => {
       return exit0();
     }
 
-    // Parse transcript
-    const { filesEdited, bashCommands, errorsEncountered, toolCallCount, readFailed } = parseTranscript(transcriptPath);
+    // Parse transcript (single read — rawText is reused by the
+    // recall-effectiveness block below)
+    const { filesEdited, bashCommands, errorsEncountered, toolCallCount, readFailed, rawText: transcriptRawText } = parseTranscript(transcriptPath);
 
     // An unreadable transcript is NOT a quiet session: the capture was
     // LOST (permissions, I/O), and a heartbeat here would keep doctor green
@@ -354,14 +362,21 @@ process.stdin.on('end', async () => {
       // entities_fts too. This copy used to insert entity + observations + tags
       // only, skipping the FTS reindex the sibling hooks did — which left every
       // session-insight memory unrecallable via the FTS keyword path.
-      function storeMemory(name, type, observations, tags) {
+      function storeMemory(name, type, observations, tags, title) {
         // null = the entity row could not be resolved = this write did NOT
         // happen (captureEntity's contract). A run with a failed write must
         // not stamp the heartbeat below — "alive" would be a lie about the
         // exact thing the heartbeat certifies.
-        if (!captureEntity(db, { name, type, observations, tags })) writeFailed = true;
+        if (!captureEntity(db, { name, type, observations, tags, title })) writeFailed = true;
       }
 
+      // No free-form human text exists for these three entities the way a
+      // commit subject does — title is synthesized from the same structured
+      // counts the observations already report. date+project+verb, per the
+      // heuristic the design settled on for hooks with no natural title source.
+      const titleDate = new Date().toISOString().slice(0, 10);
+      const titlePrefix = `${titleDate} ${projectName}`;
+
       // Rule 1: File editing session summary
       if (filesEdited.length > 0) {
         storeMemory(
@@ -371,7 +386,8 @@ process.stdin.on('end', async () => {
             `Session edited ${filesEdited.length} file(s): ${filesEdited.join(', ')}`,
             `Total tool calls: ${toolCallCount}`,
           ],
-          [...baseTags, ...fileTagsFor(filesEdited)]
+          [...baseTags, ...fileTagsFor(filesEdited)],
+          truncateTitle(`${titlePrefix}: edited ${filesEdited.length} file(s)`)
         );
       }
 
@@ -384,7 +400,8 @@ process.stdin.on('end', async () => {
             `Fixed ${errorsEncountered.length} error(s) by editing ${filesEdited.join(', ')}`,
             ...errorsEncountered.slice(0, 3).map(e => `Error: ${e.slice(0, 100)}`),
           ],
-          [...baseTags, 'type:bugfix', ...fileTagsFor(filesEdited)]
+          [...baseTags, 'type:bugfix', ...fileTagsFor(filesEdited)],
+          truncateTitle(`${titlePrefix}: fixed ${errorsEncountered.length} error(s)`)
         );
       }
 
@@ -397,7 +414,8 @@ process.stdin.on('end', async () => {
             `Significant session: ${toolCallCount} tool calls, ${filesEdited.length} files edited`,
             ...bashCommands.slice(0, 3).map(c => `Command: ${c}`),
           ],
-          [...baseTags, 'type:heavy-session']
+          [...baseTags, 'type:heavy-session'],
+          truncateTitle(`${titlePrefix}: significant session (${toolCallCount} tool calls)`)
         );
       }
 
@@ -458,43 +476,58 @@ process.stdin.on('end', async () => {
         }
 
         if (injectedData) {
-          const { entityIds, entityNames } = injectedData;
+          const { entityIds } = injectedData;
 
           if (entityIds && entityIds.length > 0) {
             // Check if recall_hits column exists (v4.0+ migration)
             const colCheck = db.prepare("PRAGMA table_info(entities)").all();
             if (colCheck.some(c => c.name === 'recall_hits')) {
               // Drop the records Claude Code created FROM our own hook
-              // output before matching. One SessionStart injection lands in
-              // the transcript 2+ times (hook_success + hook_additional_context),
-              // so any count-based discount depends on guessing an
-              // undocumented internal — get it wrong and every entity scores
-              // a hit instead of a miss. Structural removal is copy-count
-              // and encoding independent.
-              const sessionText = stripHookEchoes(readFileSync(transcriptPath, 'utf8')).toLowerCase();
-
-              // Hit/miss decision lives in `isRecallHit` (exported, unit-tested).
-
+              // output before scanning: the injected block itself prints a
+              // `[mem:id]` handle on every line, and counting those would
+              // score every injection as a hit. Structural removal is
+              // copy-count and encoding independent. Reuse the raw text
+              // parseTranscript already read — a second readFileSync
+              // doubles the Stop hook's I/O on 47MB transcripts.
+              const sessionText = stripHookEchoes(transcriptRawText);
+
+              // Citation accounting. A hit is an EXPLICIT `[mem:id]` marker
+              // the agent wrote for an id this session injected — the
+              // instruction line session-start appends after the fenced
+              // block. Literal-content matching (the previous accounting)
+              // was retired after measuring 0% signal across ten real
+              // sessions and three matching strategies: every injected
+              // memory drifted toward an unearned recall_miss, and misses
+              // feed the impact factor in core ranking.
+              //
+              // Markers are self-reported: an agent that used a memory
+              // silently earns it nothing, so the signal UNDERCOUNTS and
+              // never overcounts. That asymmetry is why misses are FROZEN —
+              // recall_misses stays untouched until measured marker
+              // compliance (the counters below) justifies reading silence
+              // as non-use. The mode stamp keeps the two eras of numbers
+              // apart.
+              const cited = extractCitedMemoryIds(sessionText);
               const updateHit = db.prepare(
                 'UPDATE entities SET recall_hits = COALESCE(recall_hits, 0) + 1 WHERE id = ?'
               );
-              const updateMiss = db.prepare(
-                'UPDATE entities SET recall_misses = COALESCE(recall_misses, 0) + 1 WHERE id = ?'
-              );
-
-              for (let i = 0; i < entityIds.length; i++) {
-                const name = (entityNames[i] || '').toLowerCase();
-                // Skip names that carry no recall signal: too short, or a
-                // machine identifier (auto-capture entities) that can never
-                // substring-match prose. Scoring those would be a guaranteed
-                // unearned miss — see isMeasurableRecallName.
-                if (!isMeasurableRecallName(name)) continue;
-                if (isRecallHit(sessionText, name)) {
-                  updateHit.run(entityIds[i]);
-                } else {
-                  updateMiss.run(entityIds[i]);
-                }
+              for (const id of entityIds) {
+                if (cited.has(id)) updateHit.run(id);
               }
+
+              // Accounting-mode stamp (constant value, rewritten every
+              // session so it survives DB restores from either era) plus
+              // the compliance denominators: sessions that HAD an injection
+              // vs sessions whose transcript carried any citation marker.
+              db.prepare(
+                'INSERT OR REPLACE INTO memesh_metadata (key, value) VALUES (?, ?)'
+              ).run('recall_accounting_mode', 'citation-v1 since 2026-08-16');
+              const bump = db.prepare(
+                `INSERT INTO memesh_metadata (key, value) VALUES (?, '1')
+                 ON CONFLICT(key) DO UPDATE SET value = CAST(CAST(value AS INTEGER) + 1 AS TEXT)`
+              );
+              bump.run('citation_sessions_total');
+              if (cited.size > 0) bump.run('citation_sessions_cited');
             }
           }
         }
@@ -671,15 +704,15 @@ function dreamHistoryPath() {
   // is in pure string comparisons, which we don't do here. The trace
   // below shows the resolved value verbatim so a Windows diagnosis run
   // can confirm what actually arrived.
-  const fromEnv = process.env.MEMESH_DIR;
-  const fromDbPath = !fromEnv ? getMemeshDirFromDbPath() : null;
-  const fromHome = (!fromEnv && !fromDbPath)
-    ? join(os.homedir() || (os.userInfo()?.homedir ?? '.'), '.memesh')
-    : null;
-  const dir = fromEnv || fromDbPath || fromHome;
+  // The helper IS the precedence (MEMESH_DB_PATH > MEMESH_DIR > home).
+  // A hand-rolled version here inverted it (MEMESH_DIR won over
+  // MEMESH_DB_PATH), so with both set, dream history landed in a different
+  // directory than every sibling state file — plus a dead home-fallback
+  // branch, since the helper always returns a string.
+  const dir = getMemeshDirFromDbPath();
   dreamTrigTrace('resolve', {
-    src: fromEnv ? 'env' : (fromDbPath ? 'db-path' : 'home'),
-    MEMESH_DIR: fromEnv,
+    src: process.env.MEMESH_DB_PATH ? 'db-path' : (process.env.MEMESH_DIR ? 'env' : 'home'),
+    MEMESH_DIR: process.env.MEMESH_DIR,
     MEMESH_DB_PATH: process.env.MEMESH_DB_PATH,
     dir,
     platform: process.platform,
@@ -807,51 +840,6 @@ export function stripHookEchoes(rawTranscript) {
   return kept.join('\n');
 }
 
-/**
- * Did the session actually USE the memory named `name`, or does the name only
- * appear because memesh injected it at session start?
- *
- * The caller passes `sessionText` with memesh's own SessionStart injection
- * already stripped structurally (see `stripHookEchoes` — matches on
- * `attachment.type`, so it is independent of JSON escaping and of how many
- * times Claude Code echoes one injection). That removal is what stops an
- * injected name from scoring a false hit; once the echo is gone, a plain
- * substring match is the whole test.
- *
- * (This replaced an earlier `transcript.replace(injectedBlob, '')` + match,
- * which silently failed on JSON-encoded transcripts and scored every entity a
- * hit — see the callsite comment.)
- *
- * Self-contained for its unit tests: lowercases both sides and ignores names
- * shorter than 4 chars (too generic to match reliably).
- */
-export function isRecallHit(sessionText, name) {
-  if (!name || name.length < 4) return false;
-  return String(sessionText ?? '').toLowerCase().includes(String(name).toLowerCase());
-}
-
-/**
- * Whether an injected entity's NAME can serve as a recall-effectiveness signal.
- *
- * Recall-effectiveness decides "was this injected memory used?" by substring-
- * matching the entity NAME in the session transcript (isRecallHit). That only
- * works for names a human might type. Auto-capture entities are named with
- * machine identifiers — `session-<pid>-<ts>-files`, `commit-<hash>`,
- * `pre-compact-<id>` — which never appear verbatim in conversation prose, so
- * they take a `recall_miss` they didn't earn on every injection. Over repeated
- * sessions that drags their Laplace-smoothed impact factor (scoring.ts, 10%
- * weight) down and quietly suppresses auto-captured memories from future recall.
- *
- * We can't measure their usefulness by name, so we don't count them either way —
- * they keep the neutral 0.5 impact. The prefix set is coupled to the auto-capture
- * producers' `<kind>-<id>` naming (post-commit / session-summary / pre-compact);
- * a new auto-capture producer should add its prefix here.
- */
-export function isMeasurableRecallName(name) {
-  if (!name || name.length < 4) return false;
-  return !/^(session-|commit-|pre-compact-)/i.test(name);
-}
-
 export function maybeTriggerDream(projectName, config, pluginRoot) {
   dreamTrigTrace('enter', { projectName, hasLlm: Boolean(config?.llm) });
   if (!projectName || projectName === 'unknown') {

package/skills/memesh/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: memesh
-description: Use MeMesh to remember, recall, and manage AI knowledge across sessions. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, or analyze work patterns. Also triggers proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
+description: Use MeMesh to remember, recall, and manage AI knowledge across sessions. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, or analyze work patterns. Also triggers when the user asks "what do you remember", "where did we leave off", or wants to catch up on a project; when a session starts and project context is needed; and proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
 user-invocable: true
 ---
 
 # MeMesh — AI Memory Management
 
-Persistent memory layer for AI agents. Remember decisions, recall context, learn from mistakes — across sessions.
+Persistent memory for AI agents. The point is continuity: the next session starts where this one stopped, instead of re-spending thousands of tokens re-discovering project state — and the human never has to re-explain it.
 
 ## How to Access (auto-detect)
 
@@ -23,39 +23,85 @@ Persistent memory layer for AI agents. Remember decisions, recall context, learn
 
 All examples below use CLI. MCP tools accept the same parameters as JSON objects.
 
+## The Loop
+
+Four moments. Everything else in this file is detail.
+
+**SESSION START → load the briefing (once).**
+Call the `briefing` MCP tool or run `memesh briefing`. It returns the assembled
+work topology: where the work was left off (goal / next / blocked / done),
+decisions and direction, lessons not to repeat, what is known, recent activity.
+One call is cheaper than re-exploring the repo to reconstruct the same picture.
+Exception: under Claude Code the session-start hook has ALREADY injected this
+exact block — do not call it again (see "What's Already Automatic").
+
+**USER STATES a goal, next step, or blocker → record it immediately.**
+```bash
+memesh task --goal "Ship the work-topology injection" --next "Open the PR once CI is green"
+memesh task --blocked "Waiting on the Windows runner"
+memesh task --blocked ""      # blocker resolved — empty string clears the field
+```
+Fields: `--goal` `--next` `--blocked` `--done` (MCP tool: `task_state`).
+Record ONLY what the user actually said. This state is injected at the top of
+the next session and read as fact — a goal you guessed from which files were
+edited reaches that session with nothing to correct it. If it was not said,
+leave the field out.
+
+**SESSION END or milestone → make the task state match reality.**
+`memesh task` (no flags) shows exactly what the next session will be told.
+If "next" is now done, record what is actually next; if the blocker cleared,
+clear it.
+
+**USER ASKS "what do you remember / where were we" → briefing, then relay.**
+Run `memesh briefing` (or `--project <name>`) and answer from it. For specific
+follow-up questions, use `recall`.
+
+**MEMESH UNAVAILABLE or RECALL EMPTY → say so, never invent.** Report that
+memory is unavailable (or found nothing) and continue without it. Never
+fabricate a memory or cite a `[mem:id]` that was not actually returned.
+Recall is bounded by `limit` — a small hit count is not a graph-wide count,
+and an empty result is not proof nothing was stored: vary the wording or
+narrow by tag before concluding. Every recall answer includes a `retrieval`
+block — `truncated: true` means the window filled (more may exist);
+`degraded: true` means semantic search could not run and these are
+keyword-only results right now (`memesh doctor` explains why).
+
 ## What's Already Automatic (Claude Code Plugin Hooks)
 
 If MeMesh is installed as a Claude Code plugin, these happen **without any action from you**:
 
 | Hook | When | What it does |
 |------|------|-------------|
-| **SessionStart** | Every session begins | Auto-recalls top memories for current project + surfaces lesson warnings |
-| **PreToolUse (Edit)** | Before editing files | Injects memories related to the file or project |
-| **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages: en, es, fr, pt, zh-TW) and reminds Claude to use memesh |
-| **PostToolUse (Commit)** | After `git commit` | Auto-tracks commit with diff stats as a memory entity |
+| **SessionStart** | Every session begins | Injects the briefing: task state → lessons → project memories → recent activity |
+| **PreToolUse (Edit/Write)** | Before editing files | Injects memories related to the file or project |
+| **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages) and reminds Claude to use memesh |
+| **PostToolUse (Bash)** | After `git commit` | Auto-tracks the commit with diff stats as a memory entity |
 | **Stop** | Session ends | Auto-captures session knowledge + runs LLM failure analysis → lessons |
-| **PreCompact** | Before context compaction | Saves important knowledge before conversation history is compressed |
-
-**You do NOT need to manually:**
-- Recall at session start (SessionStart hook does it)
-- Remember commits (PostToolUse hook does it)
-- Summarize sessions (Stop hook does it)
-- Remember when you say "記下來" / "remember this" (UserPromptSubmit hook reminds Claude)
+| **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
+| **PreToolUse (Bash)** | Before a command runs | Fires accepted lesson-guards — warns when a recorded mistake is about to repeat |
 
-**You DO need to manually** use the commands below for intentional knowledge management.
+Because of the SessionStart hook: **in Claude Code, do NOT call `briefing` at
+session start — it is already in your context.** Call it only mid-session
+(context was compacted, or the user asks what you remember) or on hosts
+without these hooks (other MCP clients, shell-only agents). Double-injection
+spends the very tokens this system exists to save.
 
-## When to Use
+Hooks capture what *happened*. You still act manually for what they cannot
+know: what the user **meant** (task state), deliberate decisions and lessons,
+and retiring outdated info.
 
-### Proactive triggers — do these WITHOUT being asked
+## Proactive triggers — do these WITHOUT being asked
 
 | Situation | Action |
 |-----------|--------|
+| User states what they're working on / what's next / what's blocking | `memesh task --goal "…"` / `--next "…"` / `--blocked "…"` |
 | Design decision made | `memesh remember --name "auth-choice" --type decision --obs "Use OAuth 2.0 with PKCE" --tags "project:myapp"` |
 | Bug fixed | `memesh learn --error "what broke" --fix "what fixed it" --root-cause "why" --severity major` |
-| Pattern established | `memesh remember --name "validation-pattern" --type pattern --obs "Always use Zod"` |
 | Starting work on a feature | `memesh recall "feature-name" --json` |
 | User asks "what did we decide?" | `memesh recall "topic" --tag "project:myapp"` |
-| Info is outdated | `memesh forget --name "old-decision"` |
+| User asks "where did we leave off?" | `memesh briefing` → relay it |
+| Info is outdated | New memory with `--supersedes "old-name"`, or `memesh forget` |
+| Context about the user's work habits needed | `user_patterns` MCP tool (MCP/HTTP only — no CLI command) |
 
 ### When NOT to remember
 - Trivial implementation details (variable names, import paths)
@@ -69,83 +115,69 @@ If MeMesh is installed as a Claude Code plugin, these happen **without any actio
 memesh learn \
   --error "SIGSEGV when running vitest with threads" \
   --fix "Use pool: 'forks' instead of 'threads' for native modules" \
-  --root-cause "better-sqlite3 native module is not thread-safe" \
-  --prevention "Check if test framework supports native modules before choosing pool" \
+  --root-cause "the native module is not thread-safe" \
+  --prevention "Check if the test framework supports native modules before choosing pool" \
   --severity major
 ```
-This creates a `lesson_learned` entity. Lessons are surfaced as **proactive warnings** at next session start.
-
-### You need context before working
-```bash
-memesh recall "authentication" --json
-memesh recall --tag "project:myapp" --limit 10
-memesh recall --cross-project                # search across all projects
-```
-Results are ranked by relevance, recency, frequency, confidence, and recall impact.
+Creates a `lesson_learned` entity. Lessons are surfaced as **proactive warnings** at the next session start.
 
 ### A decision was just made
 ```bash
 memesh remember \
-  --name "db-choice-2026" \
-  --type decision \
+  --name "db-choice" --type decision \
+  --title "SQLite for local-first storage" \
   --obs "Use SQLite for local-first" "Rejected PostgreSQL due to deployment complexity" \
   --tags "project:myapp" "topic:database"
 ```
+Use a **stable name** (`db-choice`, not `db-choice-2026-08-16`): reusing the
+name appends to the same entity instead of scattering duplicates. `--title` is
+the human-readable headline; the name stays the machine key. If this replaces
+an older decision, add `--supersedes "old-db-choice"`.
 Types: `decision` `pattern` `lesson_learned` `bug_fix` `architecture` `convention` `feature` `best_practice` `concept` `tool` `note`
 
-### Old info needs updating
+### You need context on a specific topic
 ```bash
-memesh forget --name "old-auth-approach"                    # archive entire entity
-memesh forget --name "auth-approach" --observation "Use JWT" # remove one fact only
+memesh recall "authentication" --json
+memesh recall --tag "project:myapp" --limit 10
+memesh recall --cross-project                # search across all projects
 ```
-Archives (soft-delete). Never permanently removes.
+Query words are OR-ed and ranked by relevance — a naturally phrased question
+works; extra words narrow the ranking, not the result set.
 
-### Memories are getting verbose
+### Old info needs updating
 ```bash
-memesh dream run --project myapp   # propose digests for clusters of noisy memories
-memesh dream run --from-transcripts # OR: mine this project's Claude Code sessions for memory
-memesh dream list                  # review what it proposed
-memesh dream show <id>             # inspect one proposal in full before accepting
-memesh dream accept <id>           # apply one, or: memesh dream reject <id>
+memesh forget --name "auth-approach" --observation "Use JWT"   # remove one fact only
+memesh forget --name "old-auth-approach"                       # archive the whole entity
 ```
-Nothing changes until a proposal is accepted, and sources are archived rather
-than deleted. Requires Smart Mode configured. Works on episodic memories
-(commits, session notes) — lessons, decisions, architecture notes and pinned
-entities are never touched.
+Both are soft (recoverable) — nothing is permanently removed.
 
-`memesh consolidate` was retired: it rewrote a memory with an LLM summary and
-deleted the originals on the spot, with no review step.
+### Memories are getting verbose or stale
+Use the **memesh-review** skill: it analyzes health, finds stale, conflicting
+and redundant memories, and proposes cleanup (including `memesh dream`, the
+reviewed digest pipeline). Do not hand-compress memories yourself.
 
-### Backup or share memories
+### Backup, share, health
 ```bash
 memesh export --tag "project:myapp" > memories.json
-memesh import memories.json --merge skip    # skip | overwrite | append
-```
-
-### Check MeMesh health
-```bash
-memesh status                               # version, search level, embeddings
-memesh config list                          # current configuration
+memesh import memories.json --merge skip     # skip | overwrite | append
+memesh status                                # version, search level, embeddings
+memesh reindex                               # rebuild embeddings after provider change
 ```
 
-### Regenerate embeddings after provider change
-```bash
-memesh reindex                              # rebuild all embeddings
-memesh reindex --namespace personal         # reindex only one namespace
-memesh reindex --json                       # structured progress output
-```
-Use this when you change embedding provider (e.g., Ollama → OpenAI) or dimension. The database auto-drops old embeddings on provider change, but you need to run `reindex` to regenerate them for existing memories.
-
-## MCP-Only Features
-
-These require MCP tools or the HTTP API (`memesh serve` + REST calls):
-
-- **user_patterns** — Analyzes work patterns (schedule, tool preferences, strengths) from existing memories. Categories: `workSchedule`, `toolPreferences`, `strengths`, `focusAreas`.
-
-## Best Practices
-
-1. **Be specific** — "Use OAuth 2.0 with PKCE" not "auth stuff decided"
-2. **Tag by project** — Always include `project:<name>` tag
-3. **Use `--json`** — When you need to parse output programmatically
-4. **Learn from every bug** — Every fix is a future warning. Use `learn`, not just `remember`.
-5. **Don't over-remember** — Decisions that took > 5 minutes. Patterns worth preserving. Not trivia.
+## Memory hygiene
+
+1. **Stable names append.** Remembering under an existing name adds
+   observations and dedupes tags — it never replaces the entity. Reuse the
+   name to grow one memory; do not mint `-v2` / dated variants of it.
+2. **`supersedes` retires the loser.** When a new memory replaces an old one,
+   record it with `--supersedes <old-name>` (MCP: a relation of type
+   `supersedes`). The old entity is archived — recoverable, out of recall.
+3. **`contradicts` flags real conflicts.** When two memories cannot both be
+   true and neither is clearly wrong yet, link them with `--contradicts`
+   (MCP: relation type `contradicts`). Both surface as a conflict on every
+   recall until someone resolves it.
+4. **Prefer observation-level forgetting.** `forget --observation "…"` removes
+   one wrong fact and keeps the entity. Plain `forget` archives the whole
+   entity out of visibility — use it only when everything in it is dead.
+5. **Tag by project** (`project:<name>`) and **be specific** — "Use OAuth 2.0
+   with PKCE", not "auth stuff decided".