@fingerskier/augment 0.1.9 → 0.2.0

package/dist/sleep.js

@@ -0,0 +1,129 @@
+import { cosineSimilarity } from "./util/text.js";
+export function clusterSleepCandidates(input) {
+    const byProject = new Map();
+    for (const memory of input.memories) {
+        const group = byProject.get(memory.project_name) ?? [];
+        group.push(memory);
+        byProject.set(memory.project_name, group);
+    }
+    const clusters = [];
+    for (const [projectName, group] of byProject) {
+        clusters.push(...clusterProject(projectName, group, input));
+    }
+    return clusters.sort((a, b) => b.members.length - a.members.length || a.oldest.localeCompare(b.oldest));
+}
+function clusterProject(projectName, group, input) {
+    const indexById = new Map(group.map((memory, index) => [memory.id, index]));
+    const parent = group.map((_, index) => index);
+    const find = (index) => (parent[index] === index ? index : (parent[index] = find(parent[index])));
+    const union = (a, b) => {
+        parent[find(a)] = find(b);
+    };
+    const linkEdges = new Set();
+    for (const link of input.links) {
+        const from = indexById.get(link.from_memory_id);
+        const to = indexById.get(link.to_memory_id);
+        if (from !== undefined && to !== undefined && from !== to) {
+            union(from, to);
+            linkEdges.add(edgeKey(from, to));
+        }
+    }
+    // O(n^2) pairwise cosine over one project's settled WORK memories. At the
+    // observed corpus scale (tens of WORK per project) this is microseconds;
+    // revisit only if a single project's eligible set approaches ~1k.
+    const cosineEdges = new Set();
+    const cosines = new Map();
+    for (let a = 0; a < group.length; a += 1) {
+        const vectorA = input.embeddings.get(group[a].id);
+        if (!vectorA) {
+            continue;
+        }
+        for (let b = a + 1; b < group.length; b += 1) {
+            const vectorB = input.embeddings.get(group[b].id);
+            if (!vectorB) {
+                continue;
+            }
+            const cosine = cosineSimilarity(vectorA, vectorB);
+            cosines.set(edgeKey(a, b), cosine);
+            if (cosine >= input.minCosine) {
+                union(a, b);
+                cosineEdges.add(edgeKey(a, b));
+            }
+        }
+    }
+    const components = new Map();
+    for (let index = 0; index < group.length; index += 1) {
+        const root = find(index);
+        components.set(root, [...(components.get(root) ?? []), index]);
+    }
+    const clusters = [];
+    for (const component of components.values()) {
+        if (component.length < 2) {
+            continue; // a singleton has nothing to consolidate with
+        }
+        const members = component
+            .map((index) => group[index])
+            .sort((a, b) => a.updated_at.localeCompare(b.updated_at))
+            .map((memory) => ({
+            id: memory.id,
+            relative_path: memory.relative_path,
+            name: memory.name,
+            updated_at: memory.updated_at,
+            size: memory.size,
+        }));
+        let cosineSum = 0;
+        let cosinePairs = 0;
+        for (let x = 0; x < component.length; x += 1) {
+            for (let y = x + 1; y < component.length; y += 1) {
+                const cosine = cosines.get(edgeKey(component[x], component[y]));
+                if (cosine !== undefined) {
+                    cosineSum += cosine;
+                    cosinePairs += 1;
+                }
+            }
+        }
+        const inComponent = new Set(component);
+        clusters.push({
+            project_name: projectName,
+            members,
+            mean_cosine: cosinePairs > 0 ? cosineSum / cosinePairs : 0,
+            link_edges: countEdges(linkEdges, inComponent),
+            cosine_edges: countEdges(cosineEdges, inComponent),
+            oldest: members[0].updated_at,
+            newest: members[members.length - 1].updated_at,
+        });
+    }
+    return clusters;
+}
+function edgeKey(a, b) {
+    return a < b ? `${a}:${b}` : `${b}:${a}`;
+}
+function countEdges(edges, component) {
+    let count = 0;
+    for (const key of edges) {
+        const [a, b] = key.split(":").map(Number);
+        if (component.has(a) && component.has(b)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+export function renderSleepCandidatesText(clusters, eligible, minCosine, minAgeDays) {
+    if (clusters.length === 0) {
+        return (`No sleep candidates: ${eligible} eligible WORK memories ` +
+            `(>=${minAgeDays}d settled), none connected by links or cosine>=${minCosine}. Nothing to consolidate.\n`);
+    }
+    let out = `Sleep candidates (READ-ONLY preview — nothing is consolidated or modified; ` +
+        `${eligible} eligible WORK memories >=${minAgeDays}d settled, cosine>=${minCosine}):\n`;
+    clusters.forEach((cluster, index) => {
+        out +=
+            `\n[cluster:${index + 1} project:${cluster.project_name} members:${cluster.members.length} ` +
+                `mean_cosine:${cluster.mean_cosine.toFixed(2)} edges:${cluster.link_edges}link/${cluster.cosine_edges}cosine ` +
+                `window:${cluster.oldest.slice(0, 10)}..${cluster.newest.slice(0, 10)}]\n`;
+        for (const member of cluster.members) {
+            out += `  - ${member.relative_path} (${member.updated_at.slice(0, 10)}, ${member.size} chars)\n`;
+        }
+    });
+    return out;
+}
+//# sourceMappingURL=sleep.js.map

package/dist/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../src/sleep.ts"],"names":[],"mappings":"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"}

package/dist/tally.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Phase-2 dogfood tally (council 2026-06-30): ~30 human-scored datapoints over
+ * ~2 weeks of real use, per injection surface, never a CI gate. Data lives as
+ * JSONL under `<stateDir>/tally/` — deliberately OUTSIDE the memory corpus so
+ * the corpus Phase 2 measures stays clean.
+ */
+export declare const TALLY_TARGET = 30;
+export declare const TALLY_VERDICTS: readonly ["helpful", "harmless", "harmful", "correct-abstention"];
+export type TallyVerdict = (typeof TALLY_VERDICTS)[number];
+/** One human rating of a recall outcome. */
+export interface TallyRating {
+    ts: string;
+    verdict: TallyVerdict;
+    /** Injection surface being rated: user-prompt-submit | pre-tool-use | mcp-search | cli-recall | unknown. */
+    surface: string;
+    note?: string;
+}
+/** One automatically-logged injection event (what search actually returned). */
+export interface TallyEvent {
+    ts: string;
+    surface: string;
+    project?: string;
+    /** Query text, truncated by the writer — context for later audit, not for ranking. */
+    query: string;
+    abstained: boolean;
+    result_count: number;
+    top_score?: number;
+    /** Durable relative paths of the memories injected. */
+    paths: string[];
+}
+export interface TallySummary {
+    total: number;
+    target: number;
+    by_verdict: Record<TallyVerdict, number>;
+    by_surface: Record<string, number>;
+    first_at?: string;
+    last_at?: string;
+}
+export declare function isTallyVerdict(value: unknown): value is TallyVerdict;
+export declare function ratingsPath(stateDir: string): string;
+export declare function eventsPath(stateDir: string): string;
+export declare function appendTallyRating(stateDir: string, rating: TallyRating): Promise<void>;
+export declare function appendTallyEvent(stateDir: string, event: TallyEvent): Promise<void>;
+export declare function readTallyRatings(stateDir: string): Promise<TallyRating[]>;
+export declare function summarizeTally(ratings: TallyRating[]): TallySummary;
+export declare function renderTallySummary(summary: TallySummary): string;

package/dist/tally.js

@@ -0,0 +1,94 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Phase-2 dogfood tally (council 2026-06-30): ~30 human-scored datapoints over
+ * ~2 weeks of real use, per injection surface, never a CI gate. Data lives as
+ * JSONL under `<stateDir>/tally/` — deliberately OUTSIDE the memory corpus so
+ * the corpus Phase 2 measures stays clean.
+ */
+export const TALLY_TARGET = 30;
+export const TALLY_VERDICTS = ["helpful", "harmless", "harmful", "correct-abstention"];
+export function isTallyVerdict(value) {
+    return typeof value === "string" && TALLY_VERDICTS.includes(value);
+}
+export function ratingsPath(stateDir) {
+    return path.join(stateDir, "tally", "ratings.jsonl");
+}
+export function eventsPath(stateDir) {
+    return path.join(stateDir, "tally", "events.jsonl");
+}
+async function appendLine(file, record) {
+    await mkdir(path.dirname(file), { recursive: true });
+    await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
+}
+export async function appendTallyRating(stateDir, rating) {
+    await appendLine(ratingsPath(stateDir), rating);
+}
+export async function appendTallyEvent(stateDir, event) {
+    await appendLine(eventsPath(stateDir), event);
+}
+export async function readTallyRatings(stateDir) {
+    let raw;
+    try {
+        raw = await readFile(ratingsPath(stateDir), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const ratings = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim()) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            if (isTallyVerdict(parsed.verdict)) {
+                ratings.push(parsed);
+            }
+        }
+        catch {
+            // A corrupt line loses one datapoint, never the tally.
+        }
+    }
+    return ratings;
+}
+export function summarizeTally(ratings) {
+    const by_verdict = {
+        helpful: 0,
+        harmless: 0,
+        harmful: 0,
+        "correct-abstention": 0,
+    };
+    const by_surface = {};
+    for (const rating of ratings) {
+        by_verdict[rating.verdict] += 1;
+        by_surface[rating.surface || "unknown"] = (by_surface[rating.surface || "unknown"] ?? 0) + 1;
+    }
+    return {
+        total: ratings.length,
+        target: TALLY_TARGET,
+        by_verdict,
+        by_surface,
+        ...(ratings.length > 0
+            ? { first_at: ratings[0].ts, last_at: ratings[ratings.length - 1].ts }
+            : {}),
+    };
+}
+export function renderTallySummary(summary) {
+    const lines = [
+        `Dogfood tally: ${summary.total}/${summary.target} datapoints`,
+        `  helpful: ${summary.by_verdict.helpful}  harmless: ${summary.by_verdict.harmless}  ` +
+            `harmful: ${summary.by_verdict.harmful}  correct-abstention: ${summary.by_verdict["correct-abstention"]}`,
+    ];
+    const surfaces = Object.entries(summary.by_surface)
+        .map(([surface, count]) => `${surface}:${count}`)
+        .join("  ");
+    if (surfaces) {
+        lines.push(`  by surface: ${surfaces}`);
+    }
+    if (summary.first_at && summary.last_at) {
+        lines.push(`  window: ${summary.first_at} .. ${summary.last_at}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=tally.js.map

package/dist/tally.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tally.js","sourceRoot":"","sources":["../src/tally.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -72,6 +72,12 @@ export interface SearchInput {
      * ranks highest; raise it to demand a stronger match.
      */
     min_score?: number;
+    /**
+     * Which injection surface issued this search (user-prompt-submit,
+     * pre-tool-use, mcp-search, cli-recall). Tally instrumentation only —
+     * never affects ranking.
+     */
+    surface?: string;
 }
 export interface SearchResult {
     memory: MemoryRecord;

package/dist/util/text.d.ts

@@ -1,4 +1,7 @@
 export declare function tokens(value: string): string[];
 export declare function lexicalScore(query: string, document: string): number;
+/** lexicalScore against a pre-tokenized query — callers scoring many documents
+ * against the same query tokenize it once instead of once per document. */
+export declare function lexicalScoreWith(queryTokens: ReadonlySet<string>, document: string): number;
 export declare function cosineSimilarity(a: number[], b: number[]): number;
 export declare function clamp01(value: number): number;

package/dist/util/text.js

@@ -1,9 +1,33 @@
 const WORD_RE = /[a-z0-9_./-]+/gi;
+const SEGMENT_RE = /[/._-]+/;
+// A compound token (a file path, a dotted or dashed identifier) also contributes
+// its segments, so "/repo/src/deploy/pipeline.ts" can match a document that says
+// "src/deploy/pipeline.ts" or just "deploy pipeline". The compound itself stays
+// in the list so byte-identical mentions keep their full weight.
 export function tokens(value) {
-    return Array.from(value.toLowerCase().matchAll(WORD_RE), (match) => match[0]).filter((token) => token.length > 1);
+    const out = [];
+    for (const match of value.toLowerCase().matchAll(WORD_RE)) {
+        const token = match[0];
+        if (token.length > 1) {
+            out.push(token);
+        }
+        const segments = token.split(SEGMENT_RE);
+        if (segments.length > 1) {
+            for (const segment of segments) {
+                if (segment.length > 1) {
+                    out.push(segment);
+                }
+            }
+        }
+    }
+    return out;
 }
 export function lexicalScore(query, document) {
-    const queryTokens = new Set(tokens(query));
+    return lexicalScoreWith(new Set(tokens(query)), document);
+}
+/** lexicalScore against a pre-tokenized query — callers scoring many documents
+ * against the same query tokenize it once instead of once per document. */
+export function lexicalScoreWith(queryTokens, document) {
     if (queryTokens.size === 0) {
         return 0;
     }

package/dist/util/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/util/text.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,iBAAiB,CAAC;AAElC,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAAgB;IAC1D,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,IAAI,WAAW,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACjD,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC5C,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACjD,GAAG,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/util/text.ts"],"names":[],"mappings":"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"}

package/docs/FEATURES.md

@@ -18,7 +18,7 @@ Augment is a local RAG memory system for coding agents.
 org/repo/kind/name.md
 ```
 
-- Supported MVP kinds:
+- Supported kinds:
   - `ISSUE`
   - `ARCH`
   - `TODO`
@@ -54,43 +54,30 @@ Body text.
 - The database includes metadata, body text, embeddings, gzip density score, and
   derived link rows.
 - `Xenova/bge-small-en-v1.5` via `@huggingface/transformers` provides 384D
-  embeddings.
+  embeddings. The model revision is recorded as a tripwire constant
+  (`PINNED_MODEL_REVISION`) for reproducibility.
+- Indexing is incremental: an external edit reindexes only the changed file, a
+  full rebuild skips unchanged files by mtime, and the daemon's own writes are
+  indexed inline (no watcher round-trip).
 - The database file is rebuildable and should not be synced as canonical state.
 
 Tables:
 
-- `projects`
-  - `id`
-  - `name`
-  - `org`
-  - `repo`
-  - `source`
-- `memories`
-  - `id`
-  - `project_id`
-  - `kind`
-  - `name`
-  - `relative_path`
-  - `content_hash`
-  - `frontmatter_hash`
-  - `size`
-  - `density`
-  - `mtime`
-- `memory_embeddings`
-  - `memory_id`
-  - `model_id`
-  - `model_version`
-  - `dimensions`
-  - `vector`
-  - `embedded_hash`
-- `links`
-  - `id`
-  - `from_memory_id`
-  - `to_memory_id`
-  - `type`
+- `projects` — `id`, `name`, `org`, `repo`, `source`, `created_at`, `updated_at`.
+- `memories` — `id`, `project_id`, `kind`, `name`, `relative_path`,
+  `content_hash`, `frontmatter_hash`, `size`, `density`, `mtime`, `tags_json`,
+  `links_json`, `body`, `created_at`, `updated_at`.
+- `memory_embeddings` — `memory_id`, `model_id`, `model_version`, `dimensions`,
+  `vector_json`, `embedded_hash`, `embedded_at`.
+- `links` — `id`, `from_memory_id`, `to_memory_id`, `type`, `created_at`
+  (unique on `from` + `to` + `type`).
 
 Links are written to the source memory's frontmatter using target relative paths.
-The daemon rebuilds local `links` rows from those declarations.
+The daemon rebuilds local `links` rows from those declarations. A mutation
+(`upsert`/`link`/`unlink`) repairs only the touched memory's link subgraph, so
+link IDs survive *unrelated* mutations within a daemon run — but the touched
+memory's own outbound link IDs are reassigned each time, and all IDs churn on a
+full index rebuild. Relative paths remain the durable identity.
 
 ## Daemon
 
@@ -99,6 +86,67 @@ The daemon rebuilds local `links` rows from those declarations.
 - It exposes a localhost HTTP control endpoint.
 - It binds to `127.0.0.1`, uses a dynamic port by default, writes a discovery
   file, and serves all routes without auth (loopback-only; no token required).
+- It starts serving immediately and builds the initial index in the background
+  (a cold corpus no longer blocks hooks or clients on the port);
+  `GET /index/status` reports `{ ok, ready, error? }`.
+- Besides memory/link CRUD it serves `/health`, `/index/rebuild`, and the
+  dashboard UI.
+- Memories can be deleted via the dashboard or `DELETE /memories/:id` (the file
+  and DB row are removed and inbound frontmatter links in other memories are
+  scrubbed). Delete is deliberately **not** exposed as an MCP tool.
+
+## Dashboard
+
+A daemon-served single-page web UI for browsing and editing memories as a graph:
+
+- Project graph drills into a per-project memory subgraph (nodes colored by
+  kind, edges labeled by link type).
+- Ad hoc semantic search, memory create/edit/delete, link create/delete.
+- Launched via `augment dashboard [--no-open]`; loopback-only; honors
+  `AUGMENT_DAEMON_PORT`.
+- Fully self-contained assets (Cytoscape bundled from `node_modules`; no CDN).
+
+## CLI
+
+Run without a clone via `npx -y @fingerskier/augment <command>`:
+
+- `status` — print the resolved config (default command; `config` is an alias).
+- `install <codex|claude|all>` — wire agent integrations (see
+  [Agent Integration Installer](#agent-integration-installer)).
+- `dashboard [--no-open]` — start the daemon and open the web UI.
+- `recall "<query>" [--project <org/repo>] [--cwd <dir>] [--limit N]
+  [--max-chars N] [--min-score X]` — print the same context-injection text the
+  hooks use. No match prints the explicit abstention message ("No memory met
+  the relevance threshold …"); output is empty only on failure (daemon down,
+  blank query).
+- `hook <session-start|user-prompt-submit|pre-tool-use|stop>` — run a lifecycle
+  hook over stdin JSON. Host-wired by `install`; rarely called directly.
+- `help` — full usage.
+
+## Lifecycle Hooks
+
+Both installed integrations wire the same `hooks/hooks.json` (Claude Code and
+Codex share the event names and stdin-JSON contract). Every handler **fails
+open** — any error yields empty output and exit 0, so a broken hook can never
+break the host agent.
+
+- `SessionStart` — warms the daemon and registers the project.
+- `UserPromptSubmit` — recalls memory for the prompt and injects it as
+  `additionalContext` before the model sees the prompt.
+- `PreToolUse` (matcher `Edit|Write|Bash`) — recalls additional memory keyed to
+  the tool action (the edited file / the Bash command). Uses a raised relevance
+  floor (0.45, calibrated on the real model — tool queries are command/path
+  shaped, not prose) and injects each distinct query at most once per session.
+  Injection-only: never blocks, gates, or rewrites a tool call.
+- `Stop` — blocks the turn once with a directive to upsert a memory, then allows
+  the stop (loop-guarded per turn).
+
+Installed hook commands invoke the install-time-provisioned runtime directly
+(`node <prefix>/node_modules/@fingerskier/augment/dist/bin/augment.js hook
+<event>`) — no npm bootstrap on the hot path.
+
+The verification process for the whole flow is
+[docs/verify-memory-flow.md](verify-memory-flow.md).
 
 ## MCP Tools
 
@@ -132,11 +180,11 @@ Inputs:
 {
   project_name?: string;
   query: string;
-  limit?: number;
-  max_chars?: number;
+  limit?: number;      // default 5, max 20
+  max_chars?: number;  // default 12000, max 50000
   kinds?: Array<"ISSUE" | "ARCH" | "TODO" | "SPEC" | "WORK">;
   include_linked?: boolean;
-  min_score?: number; // 0..1 relevance floor; default 0.4, 0 disables
+  min_score?: number;  // 0..1 relevance floor; default 0.4, 0 disables
 }
 ```
 
@@ -157,11 +205,16 @@ Behavior:
 - Applies a minimum relevance threshold (`min_score`, default
   `DEFAULT_SEARCH_MIN_SCORE` = 0.4) and **abstains** when nothing clears it —
   returning no results and a "nothing injected" message rather than surfacing an
-  unrelated memory. An orthogonal/unrelated memory floors at ~0.275, so the
-  default sits above that floor. Pass `min_score: 0` to disable the floor (never
-  abstain), or raise it to demand a stronger match. The default is provisional
-  and intended for calibration against the real embedding model.
-- Does not summarize or extract arbitrary excerpts.
+  unrelated memory. The floor is calibrated against the real embedding model:
+  after the empirically-anchored cosine rescale (`SEMANTIC_COSINE_BASELINE`
+  0.33), an unrelated memory blends to ~0.12 while an on-topic one lands ~0.60,
+  so 0.4 separates abstention from recall with margin. Pass `min_score: 0` to
+  disable the floor (never abstain), or raise it to demand a stronger match.
+- Packs results under a fair-share character budget: each result may use an even
+  split of the remaining `max_chars`, with unused share rolling forward; an
+  oversized body is head-truncated with a visible `[truncated]` marker rather
+  than omitted, and a result is skipped only when fewer than 80 usable characters
+  remain. Bodies are whole-file prefixes — never summarized.
 
 ### `upsert`
 
@@ -181,7 +234,15 @@ Inputs:
 ```
 
 If `memory_id` is absent, Augment may automatically update a highly similar
-memory in the same project and kind.
+memory in the same project and kind — but only when the new content subsumes the
+existing one (every distinct term of the prior body survives in the new content),
+so the in-place update is a lossless refresh. If the new content instead
+contradicts or omits something the prior memory held, Augment preserves the prior
+memory intact and stores the new content as its own memory rather than silently
+overwriting history.
+
+Content is capped at 12,000 characters; an oversized upsert is rejected — split
+the note instead.
 
 ### `read`
 
@@ -195,19 +256,24 @@ Inputs:
 
 ### `link`
 
-Creates a directional link between local memory IDs and persists it as a
-relative-path link in the source memory frontmatter.
+Creates a directional link between memories and persists it as a relative-path
+link in the source memory frontmatter.
 
 Inputs:
 
 ```ts
 {
-  from_memory_id: number;
-  to_memory_id: number;
+  from_memory_id: number | string;
+  to_memory_id: number | string;
   type?: "DEPENDS_ON" | "BLOCKS" | "IMPLEMENTS" | "PARENT" | "RELATED";
 }
 ```
 
+Each reference may be a local numeric ID **or** a relative path
+(`org/repo/KIND/name.md`). Paths are the durable handle — they survive index
+rebuilds, while numeric IDs churn. An all-digit string is interpreted as a
+numeric ID.
+
 ### `list_links`
 
 Lists inbound and outbound links involving a memory.
@@ -228,6 +294,39 @@ Inputs:
 { id: number }
 ```
 
+### `tally`
+
+Record one Phase-2 dogfood datapoint rating recalled memory quality.
+
+- Input: `verdict` (`helpful` | `harmless` | `harmful` | `correct-abstention`),
+  optional `surface`, optional `note`.
+- Returns the running tally (target: ~30 datapoints).
+- Verdict semantics: `helpful` = injected memory materially helped;
+  `harmless` = injected but neutral/ignored; `harmful` = misled or wasted
+  context; `correct-abstention` = nothing was injected, and that was right.
+- Storage: `<stateDir>/tally/ratings.jsonl` — outside the memory corpus, so
+  rating never mutates what Phase 2 measures. Every `/memories/search` also
+  appends an event line (surface, query prefix, abstained, result paths) to
+  `<stateDir>/tally/events.jsonl` for audit; event logging is best-effort and
+  can never fail a search.
+- CLI twin: `augment tally [verdict] [--surface S] [--note "..."]`; bare
+  `augment tally` prints the summary.
+
+### `sleep_candidates`
+
+READ-ONLY preview of sleep consolidation. Clusters settled WORK memories
+(default: older than 3 days by `updated_at`) within each project into candidate
+groups a future `sleep` pass would distill into SPEC/ARCH records.
+
+- Edges: existing links of any type, or raw cosine >= `min_cosine`
+  (default 0.75 — semantic-only, deliberately above the blended recall floor;
+  see `SLEEP_MIN_COSINE` in `src/constants.ts`).
+- Clusters never span projects. Output reports durable `relative_path`s.
+- Input: optional `project_name` (inferred from cwd otherwise), `min_cosine`,
+  `min_age_days`, `limit` (default 20, `SLEEP_MAX_CLUSTERS`).
+- Mutates nothing. The write-back (`sleep_apply`) is deferred behind the
+  Phase-2 dogfood go/no-go and does not exist.
+
 ## Configuration
 
 Resolution order:
@@ -267,13 +366,16 @@ Codex install creates or updates:
 - `.mcp.json` pointing to the published `@fingerskier/augment` package through
   an isolated npm `--prefix` directory.
 - `skills/augment-context/SKILL.md`.
+- `hooks/hooks.json` wiring SessionStart / UserPromptSubmit /
+  PreToolUse (`Edit|Write|Bash`) / Stop.
 - A personal or repo marketplace entry.
 
 Claude install creates or updates:
 
 - A real Claude Code plugin folder named `augment` with
   `.claude-plugin/plugin.json`, an auto-discovered `skills/augment-context/SKILL.md`,
-  and a bundled `.mcp.json` (same cwd-safe MCP command shape as Codex).
+  a bundled `.mcp.json` (same cwd-safe MCP command shape as Codex), and
+  `hooks/hooks.json` (auto-discovered lifecycle hooks).
 - A `.claude-plugin/marketplace.json` entry so the plugin is installable via
   `/plugin marketplace add` + `/plugin install augment@<marketplace>`.
 - A direct MCP registration so the server is active immediately: repo scope writes
@@ -287,11 +389,19 @@ Claude install creates or updates:
   `--no-plugin`, falling back to printing the manual `/plugin` commands.
 - A marked Augment block in `CLAUDE.md` carrying the always-on memory workflow.
 
+Both installers also provision the shared hook runtime once via
+`npm install --prefix ~/.augment/npm-exec @fingerskier/augment`, so hook commands
+run through a direct `node <entry>` invocation (tens of milliseconds) instead of
+an npm bootstrap on every event. If npm is unavailable at install time the
+installer prints the manual command; hooks fail open (silent no-ops) until it is
+run.
+
 ## Deferred
 
-- Dashboard.
-- `sleep`.
-- `dream`.
-- Remote sync.
+- `sleep` / `dream` (memory consolidation) — gated on the retrieval-quality
+  dogfood go/no-go; see [ROADMAP.md](../ROADMAP.md).
 - Memory `move`.
-- CLI aliases and UX beyond diagnostics/config helpers.
+
+Not planned:
+
+- Remote sync — file sync (e.g. Dropbox) is the supported multi-machine story.