bikky 0.3.1 → 0.3.3

package/dist/mcp/tools.js

@@ -1,11 +1,11 @@
 /**
- * MCP tool definitions — all 12 memory tools.
+ * MCP tool definitions for memory.
  */
 import crypto from "node:crypto";
 import { z } from "zod";
-import { STALENESS_DAYS, THRESHOLD_DUPLICATE, THRESHOLD_RELATED, QDRANT_INDEXES, categoryValues, domainValues, kindValues, sourceValues, DEFAULT_DOMAIN, DEFAULT_KIND, DEFAULT_SOURCE, } from "./taxonomy.js";
-import { contentHash, daysSince, lastActivityDate, computeCombinedScore, buildFilter, formatFact, } from "./helpers.js";
-import { ready, qdrantUrl, qdrantApiKey, setQdrantUrl, setQdrantApiKey, setReady, getCollection, log, embed, getEmbeddingConfig, chatComplete, qdrantReq, ensureCollection, qdrantUpsert, qdrantSearch, qdrantScroll, qdrantSetPayload, qdrantGetPoints, } from "./api.js";
+import { STALENESS_DAYS, THRESHOLD_DUPLICATE, THRESHOLD_RELATED, QDRANT_INDEXES, categoryValues, categoryEnumDescription, domainValues, domainEnumDescription, kindValues, kindEnumDescription, memorySubtypeValues, memorySubtypeEnumDescription, sourceValues, sourceEnumDescription, DEFAULT_CATEGORY, DEFAULT_DOMAIN, DEFAULT_KIND, DEFAULT_SOURCE, categoryForMemorySubtype, layerForMemorySubtype, normalizeCategory, normalizeDomain, normalizeKind, validateMemorySubtype, } from "./taxonomy.js";
+import { contentHash, daysSince, lastActivityDate, computeCombinedScore, buildFilter, formatFact, MEMORY_RECALL_EXCLUDED_KINDS, } from "./helpers.js";
+import { ready, qdrantUrl, qdrantApiKey, setupError, setQdrantUrl, setQdrantApiKey, setReady, getCollection, log, embed, getEmbeddingConfig, qdrantReq, ensureCollection, qdrantUpsert, qdrantSearch, qdrantScroll, qdrantSetPayload, qdrantGetPoints, } from "./api.js";
 import { saveConfig, loadConfig } from "../config.js";
 // ---------------------------------------------------------------------------
 // Runtime state
@@ -22,13 +22,50 @@ function nowISO() {
 function newId() {
     return crypto.randomUUID();
 }
+function redactionOptions() {
+    return { enabled: false, redactPii: false };
+}
+function redactStorageText(text) {
+    return { text, redacted: false, summary: "none", matches: [] };
+}
+function combineRedactions(_items) {
+    return { redacted: false, summary: "none", matches: [] };
+}
+function resolveScope(workspaceId, includeLegacyWorkspace = false) {
+    return {
+        workspaceId: workspaceId?.trim() || undefined,
+        includeLegacy: includeLegacyWorkspace,
+    };
+}
+function scopedFilter(scope, extra = {}) {
+    return buildFilter({
+        ...extra,
+        workspace_id: scope.workspaceId,
+        includeLegacyWorkspace: scope.includeLegacy,
+    });
+}
+function addWorkspacePayload(payload, scope) {
+    if (scope.workspaceId)
+        payload["workspace_id"] = scope.workspaceId;
+    if (scope.actorId)
+        payload["actor_id"] = scope.actorId;
+}
+function addRedactionPayload(_payload, _summary) {
+    // Task 243 keeps storage pass-through; redaction policy is out of scope for this branch.
+}
+async function getPointForWorkspaceWrite(factId, _scope) {
+    const existing = await qdrantGetPoints([factId]);
+    const point = existing.result?.[0];
+    if (!point) {
+        return { error: { status: "not_found", fact_id: factId } };
+    }
+    return { point };
+}
 function requireReady() {
     if (!ready) {
         const missing = [];
         if (!qdrantUrl)
             missing.push("qdrant-url");
-        if (!qdrantApiKey)
-            missing.push("qdrant-api-key");
         return {
             content: [{
                     type: "text",
@@ -36,6 +73,10 @@ function requireReady() {
                         status: "setup_required",
                         ready: false,
                         missing,
+                        // Surface the underlying init failure (embedding / Qdrant) when
+                        // present so users see an actionable reason instead of a generic
+                        // "setup required" message.
+                        ...(setupError ? { setup_error: setupError } : {}),
                         setup_instructions: "Memory is not configured. Run `bikky setup` or call configure_credentials:\n" +
                             "1. Go to cloud.qdrant.io → sign up (free tier: 1GB, no credit card)\n" +
                             "2. Create a cluster → copy the REST URL and API key\n" +
@@ -52,14 +93,20 @@ function buildMemoryNudge() {
     if (elapsed < NUDGE_INTERVAL_MS)
         return null;
     const mins = Math.round(elapsed / 60000);
+    // Suggest the most likely category to record based on what an engineering
+    // session typically produces. The agent picks the best fit.
     return `🧠 Memory nudge: No memory_store calls in ${mins} minutes. ` +
-        "If you've learned project facts, made key decisions, discovered service quirks, " +
-        "or resolved errors — store them now so future sessions benefit.";
+        "Reflect on what's worth persisting:\n" +
+        "  • infrastructure — new services, ports, configs touched?\n" +
+        "  • decisions — architectural choices made (with rationale)?\n" +
+        "  • observation — debugging findings, gotchas, workarounds?\n" +
+        "  • projects — work-in-progress, blockers, completions?\n" +
+        "If yes, call memory_store now so future sessions inherit the knowledge.";
 }
 /**
  * Entity-graph traversal for memory_recall.
  */
-async function graphTraversal(primaryResults, limit) {
+async function graphTraversal(primaryResults, limit, scope) {
     try {
         const primaryEntities = new Set();
         const primaryIds = new Set();
@@ -73,22 +120,16 @@ async function graphTraversal(primaryResults, limit) {
             return [];
         const relatedEntities = new Set();
         for (const entity of primaryEntities) {
-            const outgoing = await qdrantScroll({
-                must: [
-                    { key: "from_entity", match: { value: entity } },
-                    { is_null: { key: "superseded_by" } },
-                ],
-            }, 10).catch(() => ({ result: { points: [] } }));
+            const outgoingFilter = scopedFilter(scope, { excludeKinds: MEMORY_RECALL_EXCLUDED_KINDS }) ?? { must: [] };
+            outgoingFilter.must.push({ key: "from_entity", match: { value: entity } });
+            const outgoing = await qdrantScroll(outgoingFilter, 10).catch(() => ({ result: { points: [] } }));
             for (const pt of (outgoing.result?.points ?? [])) {
                 if (pt.payload.to_entity)
                     relatedEntities.add(pt.payload.to_entity);
             }
-            const incoming = await qdrantScroll({
-                must: [
-                    { key: "to_entity", match: { value: entity } },
-                    { is_null: { key: "superseded_by" } },
-                ],
-            }, 10).catch(() => ({ result: { points: [] } }));
+            const incomingFilter = scopedFilter(scope, { excludeKinds: MEMORY_RECALL_EXCLUDED_KINDS }) ?? { must: [] };
+            incomingFilter.must.push({ key: "to_entity", match: { value: entity } });
+            const incoming = await qdrantScroll(incomingFilter, 10).catch(() => ({ result: { points: [] } }));
             for (const pt of (incoming.result?.points ?? [])) {
                 if (pt.payload.from_entity)
                     relatedEntities.add(pt.payload.from_entity);
@@ -101,12 +142,9 @@ async function graphTraversal(primaryResults, limit) {
         const relatedFacts = [];
         const maxPerEntity = Math.max(2, Math.floor(limit / relatedEntities.size));
         for (const entity of relatedEntities) {
-            const result = await qdrantScroll({
-                must: [
-                    { key: "entities", match: { value: entity } },
-                    { is_null: { key: "superseded_by" } },
-                ],
-            }, maxPerEntity).catch(() => ({ result: { points: [] } }));
+            const filter = scopedFilter(scope, { excludeKinds: MEMORY_RECALL_EXCLUDED_KINDS }) ?? { must: [] };
+            filter.must.push({ key: "entities", match: { value: entity } });
+            const result = await qdrantScroll(filter, maxPerEntity).catch(() => ({ result: { points: [] } }));
             for (const pt of (result.result?.points ?? [])) {
                 if (!primaryIds.has(pt.id)) {
                     relatedFacts.push(pt);
@@ -128,7 +166,11 @@ async function graphTraversal(primaryResults, limit) {
 // ---------------------------------------------------------------------------
 export function registerTools(mcp) {
     // ── get_setup_status ────────────────────────────────────────────────────
-    mcp.tool("get_setup_status", "Check memory system status. Returns which credentials are configured and whether Qdrant and embeddings are reachable.", {}, async () => {
+    mcp.tool("get_setup_status", [
+        "Check whether the memory system is configured and reachable.",
+        "Use this when memory tools return a 'setup_required' error, or once at session start if you're not sure bikky is wired up. Reports which credentials are missing and includes onboarding instructions if anything is incomplete.",
+        "Read-only — safe to call any time.",
+    ].join(" "), {}, async () => {
         const status = {
             ready,
             qdrant_url: !!qdrantUrl,
@@ -139,13 +181,13 @@ export function registerTools(mcp) {
             embedding_provider: getEmbeddingConfig().provider,
             embedding_model: getEmbeddingConfig().model,
             embedding_dimensions: getEmbeddingConfig().dimensions,
+            ...(setupError ? { setup_error: setupError } : {}),
         };
         const missing = status["missing"];
         if (!qdrantUrl)
             missing.push("qdrant-url");
-        if (!qdrantApiKey)
-            missing.push("qdrant-api-key");
-        if (qdrantUrl && qdrantApiKey) {
+        // qdrant-api-key is optional (local / self-hosted Qdrant doesn't need it).
+        if (qdrantUrl) {
             try {
                 await qdrantReq("GET", "/collections");
                 status["qdrant_connected"] = true;
@@ -159,17 +201,21 @@ export function registerTools(mcp) {
         catch { /* ignore */ }
         if (!status["ready"] && missing.length > 0) {
             status["setup_instructions"] =
-                "Run `bikky setup` or guide the user:\n" +
-                    "1. Go to cloud.qdrant.io → sign up (free tier: 1GB, no credit card)\n" +
-                    "2. Create a cluster → copy the REST URL and API key\n" +
-                    "3. Call configure_credentials with Qdrant values";
+                "Run `bikky setup` or guide the user. Pick one Qdrant option:\n" +
+                    "  • Qdrant Cloud (managed, free tier, 1GB): https://cloud.qdrant.io — copy the REST URL + API key\n" +
+                    "  • Local Docker: `docker run -p 6333:6333 qdrant/qdrant` → URL `http://localhost:6333` (no API key needed)\n" +
+                    "  • Self-hosted: any reachable Qdrant; API key only required if QDRANT__SERVICE__API_KEY is set on the server\n" +
+                    "Then call configure_credentials with the URL (and API key if applicable).";
         }
         return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }] };
     });
     // ── configure_credentials ───────────────────────────────────────────────
-    mcp.tool("configure_credentials", "Store Qdrant + embedding credentials in ~/.bikky/config.json. Tests connectivity and creates the collection if needed.", {
-        qdrant_url: z.string().optional().describe("Qdrant Cloud REST URL (e.g. https://xxx.cloud.qdrant.io:6333)"),
-        qdrant_api_key: z.string().optional().describe("Qdrant Cloud API key"),
+    mcp.tool("configure_credentials", [
+        "Persist Qdrant and embedding credentials to ~/.bikky/config.json and bring the memory system online.",
+        "Call this only during onboarding (or when rotating credentials). After it succeeds, the collection is created if missing and embeddings are tested. For day-to-day use, prefer get_setup_status.",
+    ].join(" "), {
+        qdrant_url: z.string().optional().describe("Qdrant REST URL — Qdrant Cloud (https://xxx.cloud.qdrant.io:6333), local Docker (http://localhost:6333), or self-hosted"),
+        qdrant_api_key: z.string().optional().describe("Qdrant API key — required for Qdrant Cloud; optional / leave blank for unauthenticated local or self-hosted instances"),
         openai_api_key: z.string().optional().describe("OpenAI API key (for OpenAI embedding/LLM provider)"),
     }, async ({ qdrant_url, qdrant_api_key, openai_api_key }) => {
         const results = {};
@@ -191,7 +237,7 @@ export function registerTools(mcp) {
             results["openai_api_key"] = "stored ✓";
         }
         saveConfig(cfg);
-        if (qdrantUrl && qdrantApiKey) {
+        if (qdrantUrl) {
             try {
                 await ensureCollection(QDRANT_INDEXES);
                 results["qdrant_collection"] = `'${getCollection()}' ready ✓`;
@@ -208,14 +254,18 @@ export function registerTools(mcp) {
         catch (e) {
             results["embedding"] = `error: ${e instanceof Error ? e.message : String(e)}`;
         }
-        setReady(!!(qdrantUrl && qdrantApiKey));
+        setReady(!!qdrantUrl);
         results["ready"] = ready;
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
     });
     // ── verify_connection ───────────────────────────────────────────────────
-    mcp.tool("verify_connection", "Test that Qdrant is reachable, embeddings work, and the collection exists.", {}, async () => {
+    mcp.tool("verify_connection", [
+        "Confirm Qdrant is reachable, embeddings work, and the collection exists.",
+        "Use this to debug a sudden 'setup_required' or empty-recall after a network blip or credential change. Lighter than configure_credentials — does not write to disk.",
+        "Read-only.",
+    ].join(" "), {}, async () => {
         const results = { qdrant: false, embedding: false, collection: false };
-        if (qdrantUrl && qdrantApiKey) {
+        if (qdrantUrl) {
             try {
                 await qdrantReq("GET", "/collections");
                 results["qdrant"] = true;
@@ -242,42 +292,84 @@ export function registerTools(mcp) {
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
     });
     // ── memory_store ────────────────────────────────────────────────────────
-    mcp.tool("memory_store", "Store a new fact in memory. Automatically deduplicates via content hash and vector similarity. " +
-        "Returns the action taken (inserted/reinforced/duplicate) and any similar facts found.", {
-        content: z.string().describe("The fact to store (atomic, single piece of knowledge)"),
-        category: z.enum(categoryValues())
-            .describe("Topic: infrastructure, decisions, observation, preferences, projects, team"),
-        entities: z.array(z.string()).describe("Related entities (lowercase, e.g. ['qdrant', 'platform'])"),
-        domain: z.enum(domainValues()).default(DEFAULT_DOMAIN)
-            .describe("Life scope — work or personal"),
-        kind: z.enum(kindValues()).default(DEFAULT_KIND)
-            .describe("Knowledge form — fact, summary, distilled, relation"),
-        source: z.enum(sourceValues()).default(DEFAULT_SOURCE)
-            .describe("Creator — agent, daemon, system, user"),
-        confidence: z.number().min(0).max(1).default(0.9).describe("How certain (0.0-1.0)"),
-        importance: z.number().min(0).max(1).optional().describe("How important (0.0-1.0). Omit to default to 0.5."),
-        supersedes: z.string().optional().describe("ID of a fact this one replaces"),
+    mcp.tool("memory_store", [
+        "Persist one atomic fact to long-term memory.",
+        "Call this whenever you learn something a future session would need: a service detail, a decision rationale, a workaround, a user preference, an ownership fact, a task-resume pointer. One fact per call — split compound observations into separate calls.",
+        "Dedup is automatic (content hash + vector similarity), so you do NOT need to recall first. The tool returns one of: inserted (new fact), reinforced (exact or near-duplicate found — counters bumped), or — if there are similar-but-different facts — a list of potential conflicts so you can decide whether to use 'supersedes'.",
+        "To create a typed edge between two entities at the same time, set the optional 'relation' field — no separate tool call needed.",
+        "Do NOT use for ephemeral state (current cursor, in-flight todo). Use the harness task folder instead.",
+    ].join(" "), {
+        content: z.string().describe("The fact to store. Should be one atomic, self-contained statement (no compound 'A and B') that makes sense out of context."),
+        category: z.enum(categoryValues()).describe(categoryEnumDescription()),
+        entities: z.array(z.string()).describe("Lowercase entity names mentioned by this fact (e.g. ['qdrant', 'workspace_id']). Used for entity-scoped recall and graph traversal — keep them short and canonical."),
+        domain: z.enum(domainValues()).default(DEFAULT_DOMAIN).describe(domainEnumDescription()),
+        kind: z.enum(kindValues()).default(DEFAULT_KIND).describe(kindEnumDescription()),
+        memory_subtype: z.enum(memorySubtypeValues()).optional().describe(memorySubtypeEnumDescription()),
+        workspace_id: z.string().optional().describe("Workspace namespace for team-shared memory. Omit to use the default workspace from config."),
+        episode_id: z.string().optional().describe("Coherent activity-segment ID. Group facts captured during the same coherent task or transcript."),
+        workstream_key: z.string().optional().describe("Durable continuity key for a long-running objective (survives across sessions)."),
+        task_key: z.string().optional().describe("Task or issue key (e.g. GitHub issue number, JIRA key)."),
+        repo: z.string().optional().describe("Repository or project surface this fact relates to (e.g. 'bikky-dev/bikky')."),
+        branch: z.string().optional().describe("Branch or working surface (e.g. 'main', 'feat/x')."),
+        review_status: z.enum(["candidate", "reviewed", "approved", "rejected"]).optional().describe("Review lifecycle status. candidate=auto-extracted (daemon), reviewed=human-checked, approved=human-confirmed, rejected=incorrect. Agents normally leave this unset."),
+        source: z.enum(sourceValues()).default(DEFAULT_SOURCE).describe(sourceEnumDescription()),
+        confidence: z.number().min(0).max(1).default(0.9).describe("How certain you are this fact is correct (0.0-1.0). Default 0.9. Lower (~0.6) for inferred or unverified facts."),
+        importance: z.number().min(0).max(1).optional().describe("How important this fact is for future recall (0.0-1.0). Defaults to 0.5 if omitted. ≥0.8 surfaces in session briefings."),
+        supersedes: z.string().optional().describe("ID of an existing fact that this one replaces. The old fact is marked superseded and excluded from recall. Use this when a fact is updated; use memory_forget when a fact was simply wrong."),
         relation: z.object({
-            from: z.string().describe("Source entity"),
-            type: z.string().describe("Relation type (owns, uses, decided, prefers, works-on, etc.)"),
-            to: z.string().describe("Target entity"),
-        }).optional().describe("Optional typed relation between two entities"),
-        metadata: z.record(z.string(), z.string()).optional()
-            .describe("Optional key-value metadata. Stored with the fact and filterable via memory_recall."),
-    }, async ({ content, category, entities, domain, kind, source, confidence, importance, supersedes, relation, metadata }) => {
+            from: z.string().describe("Source entity (lowercase)."),
+            type: z.string().describe("Relation type (e.g. 'owns', 'uses', 'decided', 'prefers', 'works-on')."),
+            to: z.string().describe("Target entity (lowercase)."),
+        }).optional().describe("Optional typed edge between two entities — created in the same call. Use this whenever the fact also expresses a relationship; no separate tool call needed."),
+        metadata: z.record(z.string(), z.string()).optional().describe("Arbitrary key-value metadata. Stored with the fact and exact-match filterable via memory_recall.metadata_filter (all key/value pairs must match — AND logic)."),
+    }, async ({ content, category, entities, domain, kind, memory_subtype, workspace_id, episode_id, workstream_key, task_key, repo, branch, review_status, source, confidence, importance, supersedes, relation, metadata, }) => {
         const guard = requireReady();
         if (guard)
             return guard;
         lastStoreTime = Date.now();
         const now = nowISO();
-        const hash = contentHash(category, content);
-        const normalizedEntities = entities.map((e) => e.toLowerCase());
+        const scope = resolveScope(workspace_id);
+        const normalizedKind = normalizeKind(kind);
+        let normalizedSubtype = null;
+        try {
+            normalizedSubtype = validateMemorySubtype(normalizedKind, memory_subtype);
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                isError: true,
+            };
+        }
+        const normalizedCategory = normalizedSubtype
+            ? categoryForMemorySubtype(normalizedSubtype) ?? normalizeCategory(category)
+            : normalizeCategory(category);
+        const normalizedDomain = normalizeDomain(domain);
+        const normalizedLayer = normalizedSubtype ? layerForMemorySubtype(normalizedSubtype) : null;
+        const redactedContent = redactStorageText(content);
+        const redactedEntities = entities.map((entity) => redactStorageText(entity));
+        const sanitizedEntities = redactedEntities.map((entity) => entity.text);
+        const redactedRelation = relation ? {
+            from: redactStorageText(relation.from),
+            type: redactStorageText(relation.type),
+            to: redactStorageText(relation.to),
+        } : null;
+        const redactionSummary = combineRedactions([
+            redactedContent,
+            ...redactedEntities,
+            ...(redactedRelation ? [redactedRelation.from, redactedRelation.type, redactedRelation.to] : []),
+        ]);
+        const hash = contentHash(normalizedCategory, redactedContent.text);
+        const normalizedEntities = sanitizedEntities.map((e) => e.toLowerCase());
+        const sanitizedRelation = redactedRelation ? {
+            from: redactedRelation.from.text,
+            type: redactedRelation.type.text,
+            to: redactedRelation.to.text,
+        } : null;
         // 1. Exact dedup via content hash
         try {
-            const existing = await qdrantScroll({ must: [
-                    { key: "content_hash", match: { value: hash } },
-                    { is_null: { key: "superseded_by" } },
-                ] }, 1);
+            const hashFilter = scopedFilter(scope) ?? { must: [] };
+            hashFilter.must.push({ key: "content_hash", match: { value: hash } });
+            const existing = await qdrantScroll(hashFilter, 1);
             const existingPoint = existing.result?.points?.[0];
             if (existingPoint) {
                 const point = existingPoint;
@@ -301,17 +393,16 @@ export function registerTools(mcp) {
             log("WARN", `Hash dedup check failed: ${e instanceof Error ? e.message : String(e)}`);
         }
         // 2. Generate embedding
-        const vector = await embed(content);
+        const vector = await embed(redactedContent.text);
         // 3. Semantic dedup
         let similarFacts = [];
         let potentialConflicts = [];
         try {
-            const filter = { must: [] };
+            const filter = scopedFilter(scope) ?? { must: [] };
             if (normalizedEntities.length > 0) {
                 filter.must.push({ key: "entities", match: { any: normalizedEntities } });
             }
-            filter.must.push({ is_null: { key: "superseded_by" } });
-            const results = await qdrantSearch(vector, filter.must.length > 0 ? filter : undefined, 3);
+            const results = await qdrantSearch(vector, filter, 3);
             const firstResult = results.result?.[0];
             if (results.result?.length > 0 && firstResult) {
                 const topScore = firstResult.score ?? 0;
@@ -368,6 +459,10 @@ export function registerTools(mcp) {
         // 5. Supersede old fact if requested
         if (supersedes) {
             try {
+                const existing = await getPointForWorkspaceWrite(supersedes, scope);
+                if (existing.error) {
+                    return { content: [{ type: "text", text: JSON.stringify(existing.error, null, 2) }], isError: true };
+                }
                 await qdrantSetPayload([supersedes], {
                     superseded_by: factId,
                     superseded_at: now,
@@ -379,10 +474,10 @@ export function registerTools(mcp) {
         }
         // 6. Insert new fact
         const payload = {
-            content,
-            category,
-            domain,
-            kind,
+            content: redactedContent.text,
+            category: normalizedCategory,
+            domain: normalizedDomain,
+            kind: normalizedKind,
             entities: normalizedEntities,
             source,
             confidence,
@@ -395,22 +490,43 @@ export function registerTools(mcp) {
             created_at: now,
             updated_at: now,
         };
+        if (normalizedSubtype) {
+            payload["memory_subtype"] = normalizedSubtype;
+        }
+        if (normalizedLayer) {
+            payload["layer"] = normalizedLayer;
+        }
+        if (episode_id)
+            payload["episode_id"] = episode_id;
+        if (workstream_key)
+            payload["workstream_key"] = workstream_key;
+        if (task_key)
+            payload["task_key"] = task_key;
+        if (repo)
+            payload["repo"] = repo;
+        if (branch)
+            payload["branch"] = branch;
+        if (review_status)
+            payload["review_status"] = review_status;
+        addWorkspacePayload(payload, scope);
+        addRedactionPayload(payload, redactionSummary);
         if (metadata && Object.keys(metadata).length > 0) {
             payload["metadata"] = metadata;
         }
         await qdrantUpsert(factId, vector, payload);
         // 7. Insert relation point if provided
         let relationId = null;
-        if (relation) {
+        if (sanitizedRelation) {
             relationId = newId();
-            const relContent = `${relation.from} ${relation.type} ${relation.to}`;
+            const relContent = `${sanitizedRelation.from} ${sanitizedRelation.type} ${sanitizedRelation.to}`;
             const relVector = await embed(relContent);
             const relPayload = {
                 content: relContent,
-                category,
-                domain,
+                category: normalizedCategory,
+                domain: normalizedDomain,
                 kind: "relation",
-                entities: [relation.from.toLowerCase(), relation.to.toLowerCase()],
+                layer: "memory_object",
+                entities: [sanitizedRelation.from.toLowerCase(), sanitizedRelation.to.toLowerCase()],
                 source,
                 confidence,
                 content_hash: contentHash("relation", relContent),
@@ -420,18 +536,23 @@ export function registerTools(mcp) {
                 superseded_at: null,
                 created_at: now,
                 updated_at: now,
-                from_entity: relation.from.toLowerCase(),
-                relation_type: relation.type.toLowerCase(),
-                to_entity: relation.to.toLowerCase(),
+                from_entity: sanitizedRelation.from.toLowerCase(),
+                relation_type: sanitizedRelation.type.toLowerCase(),
+                to_entity: sanitizedRelation.to.toLowerCase(),
             };
+            addWorkspacePayload(relPayload, scope);
+            addRedactionPayload(relPayload, redactionSummary);
             await qdrantUpsert(relationId, relVector, relPayload);
         }
         const result = {
             action: "inserted",
             fact_id: factId,
+            workspace_id: scope.workspaceId,
         };
         if (relationId)
             result["relation_id"] = relationId;
+        if (redactionSummary.redacted)
+            result["redaction"] = redactionSummary;
         if (similarFacts.length > 0)
             result["similar_facts"] = similarFacts;
         if (potentialConflicts.length > 0) {
@@ -443,26 +564,72 @@ export function registerTools(mcp) {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     });
     // ── memory_recall ───────────────────────────────────────────────────────
-    mcp.tool("memory_recall", "Semantic search over memory. Returns facts ranked by relevance. " +
-        "Use on session start with a broad query for context briefing.", {
-        query: z.string().describe("What to search for (natural language)"),
-        category: z.string().optional().describe("Filter by category"),
-        domain: z.string().optional().describe("Filter by domain (work or personal)"),
-        kind: z.string().optional().describe("Filter by kind (fact, summary, distilled, relation)"),
-        entity: z.string().optional().describe("Filter by entity name"),
-        since: z.string().optional().describe("Only facts created after this ISO date"),
-        until: z.string().optional().describe("Only facts created before this ISO date"),
-        limit: z.number().optional().default(10).describe("Max results (default 10)"),
-        graph_depth: z.number().optional().default(0).describe("Entity graph traversal depth (0=none, 1=include 1-hop related entity facts)."),
-        metadata_filter: z.record(z.string(), z.string()).optional()
-            .describe("Filter by metadata key-value pairs. All pairs must match."),
-    }, async ({ query, category, domain, kind, entity, since, until, limit, graph_depth, metadata_filter }) => {
+    mcp.tool("memory_recall", [
+        "Semantic + filtered search over memory. Returns facts ranked by relevance (vector similarity blended with recency, importance, and reinforcement).",
+        "Three main uses:",
+        "  1. Session-start briefing — broad query like 'session briefing: user preferences, active projects, recent decisions'.",
+        "  2. Per-prompt contextual recall — focused query derived from what the user just asked.",
+        "  3. Pre-store conflict check — recall similar facts before storing, so you can use 'supersedes' if the new fact replaces an older one.",
+        "Combine the natural-language query with structured filters (category, domain, entity, date range, metadata) for tighter results.",
+        "If you have a known entity name and want everything about it, prefer memory_entity. For 'what does X own/use?' style questions, prefer memory_relations.",
+    ].join("\n"), {
+        query: z.string().describe("Natural-language description of what you're looking for. Embedded and matched semantically — full sentences work better than keyword lists."),
+        category: z.string().optional().describe("Filter by category (same vocabulary as memory_store.category). Optional."),
+        domain: z.string().optional().describe("Filter by domain activity profile (same vocabulary as memory_store.domain). Optional."),
+        kind: z.string().optional().describe("Filter by kind: fact, summary, distilled, relation. Optional. Telemetry is excluded by default."),
+        memory_subtype: z.string().optional().describe("Filter by memory subtype (must be valid for the chosen kind). Optional."),
+        workspace_id: z.string().optional().describe("Filter to facts in this workspace namespace. Omit to use the default workspace from config."),
+        include_legacy_workspace: z.boolean().optional().describe("Backwards-compatibility flag: also include legacy facts that have no workspace_id. Default false. Only set this if you suspect pre-migration data is missing from results."),
+        entity: z.string().optional().describe("Restrict to facts mentioning this entity (case-insensitive). For full entity context prefer memory_entity."),
+        episode_id: z.string().optional().describe("Filter by coherent episode ID."),
+        workstream_key: z.string().optional().describe("Filter by durable workstream key."),
+        task_key: z.string().optional().describe("Filter by task or issue key."),
+        repo: z.string().optional().describe("Filter by repository or project surface."),
+        branch: z.string().optional().describe("Filter by branch or working surface."),
+        review_status: z.string().optional().describe("Filter by review lifecycle status (candidate / reviewed / approved / rejected)."),
+        since: z.string().optional().describe("Only facts created on or after this ISO 8601 date or datetime."),
+        until: z.string().optional().describe("Only facts created on or before this ISO 8601 date or datetime."),
+        limit: z.number().optional().default(10).describe("Max results to return (default 10)."),
+        graph_depth: z.number().optional().default(0).describe("Entity-graph traversal depth. 0 = vector search only (fast, default). 1 = also surface 1-hop entity-related facts (slower; use when the user asks 'what's connected to X?')."),
+        metadata_filter: z.record(z.string(), z.string()).optional().describe("Exact-match filter on the metadata map stored with each fact. All key/value pairs must match (AND logic)."),
+    }, async ({ query, category, domain, kind, memory_subtype, workspace_id, include_legacy_workspace, entity, episode_id, workstream_key, task_key, repo, branch, review_status, since, until, limit, graph_depth, metadata_filter, }) => {
         const guard = requireReady();
         if (guard)
             return guard;
         const requestedLimit = limit ?? 10;
-        const vector = await embed(query);
-        const filter = buildFilter({ category, domain, kind, entity, since, until, metadata: metadata_filter });
+        const scope = resolveScope(workspace_id, include_legacy_workspace);
+        const redactedQuery = redactStorageText(query);
+        const vector = await embed(redactedQuery.text);
+        const normalizedKind = kind ? normalizeKind(kind) : undefined;
+        let normalizedSubtype;
+        if (memory_subtype) {
+            try {
+                normalizedSubtype = validateMemorySubtype(normalizedKind, memory_subtype) ?? undefined;
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
+                    isError: true,
+                };
+            }
+        }
+        const filter = scopedFilter(scope, {
+            category: category ? normalizeCategory(category) : undefined,
+            domain: domain ? normalizeDomain(domain) : undefined,
+            kind: normalizedKind,
+            memory_subtype: normalizedSubtype,
+            entity,
+            episode_id,
+            workstream_key,
+            task_key,
+            repo,
+            branch,
+            review_status,
+            since,
+            until,
+            metadata: metadata_filter,
+            excludeKinds: MEMORY_RECALL_EXCLUDED_KINDS,
+        });
         const results = await qdrantSearch(vector, filter, requestedLimit * 2);
         if (!results.result?.length) {
             const nudge = buildMemoryNudge();
@@ -475,7 +642,7 @@ export function registerTools(mcp) {
             .slice(0, requestedLimit);
         const lines = ranked.map((r) => formatFact(r));
         if ((graph_depth ?? 0) >= 1) {
-            const relatedLines = await graphTraversal(ranked, requestedLimit);
+            const relatedLines = await graphTraversal(ranked, requestedLimit, scope);
             if (relatedLines.length > 0) {
                 lines.push("", "── Related (1-hop) ──");
                 lines.push(...relatedLines);
@@ -487,28 +654,30 @@ export function registerTools(mcp) {
         return { content: [{ type: "text", text: lines.join("\n") }] };
     });
     // ── memory_entity ───────────────────────────────────────────────────────
-    mcp.tool("memory_entity", "Get everything known about an entity — all facts mentioning it plus its relationships.", {
-        name: z.string().describe("Entity name (e.g. 'qdrant', 'platform')"),
-        limit: z.number().optional().default(20).describe("Max facts to return"),
-    }, async ({ name, limit }) => {
+    mcp.tool("memory_entity", [
+        "Get everything bikky knows about a specific entity — facts mentioning it plus typed relations into and out of it.",
+        "Prefer this over memory_recall when the user asks 'tell me about X' or 'what do we know about X' and X is a known entity name (service, person, repo, concept). Faster and more complete than semantic search for entity-centric queries.",
+        "If you only have a fuzzy description, use memory_recall first to find the entity name.",
+    ].join(" "), {
+        name: z.string().describe("Entity name (case-insensitive, e.g. 'qdrant', 'workspace_id'). Should match the lowercase canonical form used when facts were stored."),
+        limit: z.number().optional().default(20).describe("Max facts to return (default 20). Relations are always returned in full, capped at 50 each direction."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+        include_legacy_workspace: z.boolean().optional().describe("Backwards-compatibility: also include legacy facts with no workspace_id. Default false."),
+    }, async ({ name, limit, workspace_id, include_legacy_workspace }) => {
         const guard = requireReady();
         if (guard)
             return guard;
         const entityName = name.toLowerCase();
-        const facts = await qdrantScroll({
-            must: [
-                { key: "entities", match: { value: entityName } },
-                { is_null: { key: "superseded_by" } },
-            ],
-        }, limit ?? 20);
-        const relationsFrom = await qdrantScroll({ must: [
-                { key: "from_entity", match: { value: entityName } },
-                { is_null: { key: "superseded_by" } },
-            ] }, 50);
-        const relationsTo = await qdrantScroll({ must: [
-                { key: "to_entity", match: { value: entityName } },
-                { is_null: { key: "superseded_by" } },
-            ] }, 50);
+        const scope = resolveScope(workspace_id, include_legacy_workspace);
+        const factsFilter = scopedFilter(scope) ?? { must: [] };
+        factsFilter.must.push({ key: "entities", match: { value: entityName } });
+        const facts = await qdrantScroll(factsFilter, limit ?? 20);
+        const fromFilter = scopedFilter(scope) ?? { must: [] };
+        fromFilter.must.push({ key: "from_entity", match: { value: entityName } });
+        const relationsFrom = await qdrantScroll(fromFilter, 50);
+        const toFilter = scopedFilter(scope) ?? { must: [] };
+        toFilter.must.push({ key: "to_entity", match: { value: entityName } });
+        const relationsTo = await qdrantScroll(toFilter, 50);
         const output = [];
         const factPoints = facts.result?.points ?? [];
         if (factPoints.length > 0) {
@@ -543,22 +712,26 @@ export function registerTools(mcp) {
         return { content: [{ type: "text", text: output.join("\n") }] };
     });
     // ── memory_relations ────────────────────────────────────────────────────
-    mcp.tool("memory_relations", "Query entity relationships. Returns typed edges between entities.", {
-        entity: z.string().describe("Entity name to query"),
-        relation_type: z.string().optional().describe("Filter by relation type (e.g. 'owns', 'uses', 'decided')"),
-        direction: z.enum(["from", "to", "both"]).optional().default("both")
-            .describe("Direction: 'from' (entity as source), 'to' (entity as target), 'both'"),
-    }, async ({ entity, relation_type, direction }) => {
+    mcp.tool("memory_relations", [
+        "Query typed edges between entities. Returns 'A --[type]--> B' triples that semantic search alone wouldn't surface.",
+        "Use for 'what does X own / use / depend on?' and 'who owns Y?' style questions. Optionally filter by direction (from / to / both) and relation type.",
+        "To create relations, use memory_store with the 'relation' field — there is no separate create-relation tool.",
+    ].join(" "), {
+        entity: z.string().describe("Entity name to query (case-insensitive)."),
+        relation_type: z.string().optional().describe("Filter to a specific edge label (e.g. 'owns', 'uses', 'decided', 'prefers', 'works-on'). Optional."),
+        direction: z.enum(["from", "to", "both"]).optional().default("both").describe("Which side of the edge the entity is on. 'from' = entity is the source (X --[?]--> ?). 'to' = entity is the target (? --[?]--> X). 'both' = either (default)."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+        include_legacy_workspace: z.boolean().optional().describe("Backwards-compatibility: also include legacy facts with no workspace_id. Default false."),
+    }, async ({ entity, relation_type, direction, workspace_id, include_legacy_workspace }) => {
         const guard = requireReady();
         if (guard)
             return guard;
         const entityName = entity.toLowerCase();
+        const scope = resolveScope(workspace_id, include_legacy_workspace);
         const results = [];
         if (direction === "from" || direction === "both") {
-            const filter = { must: [
-                    { key: "from_entity", match: { value: entityName } },
-                    { is_null: { key: "superseded_by" } },
-                ] };
+            const filter = scopedFilter(scope) ?? { must: [] };
+            filter.must.push({ key: "from_entity", match: { value: entityName } });
             if (relation_type) {
                 filter.must.push({ key: "relation_type", match: { value: relation_type.toLowerCase() } });
             }
@@ -566,10 +739,8 @@ export function registerTools(mcp) {
             results.push(...(r.result?.points ?? []));
         }
         if (direction === "to" || direction === "both") {
-            const filter = { must: [
-                    { key: "to_entity", match: { value: entityName } },
-                    { is_null: { key: "superseded_by" } },
-                ] };
+            const filter = scopedFilter(scope) ?? { must: [] };
+            filter.must.push({ key: "to_entity", match: { value: entityName } });
             if (relation_type) {
                 filter.must.push({ key: "relation_type", match: { value: relation_type.toLowerCase() } });
             }
@@ -593,38 +764,62 @@ export function registerTools(mcp) {
         return { content: [{ type: "text", text: lines.join("\n") }] };
     });
     // ── memory_forget ───────────────────────────────────────────────────────
-    mcp.tool("memory_forget", "Mark a fact as superseded/wrong. The fact remains but is excluded from recall results.", {
-        fact_id: z.string().describe("ID of the fact to forget"),
-        reason: z.string().describe("Why this fact is being superseded"),
-    }, async ({ fact_id, reason }) => {
+    mcp.tool("memory_forget", [
+        "Mark a fact as superseded/wrong. The fact stays in storage (for audit) but is excluded from all recall results.",
+        "Use this when a fact was simply incorrect or no longer applies and there is no replacement. If you have a corrected version, use memory_store with 'supersedes: <fact_id>' instead — that way the new fact stays linked to the old one.",
+    ].join(" "), {
+        fact_id: z.string().describe("ID of the fact to forget (returned by memory_store / memory_recall as 'id')."),
+        reason: z.string().describe("Short human-readable reason this fact is being retired (stored in 'superseded_by' for future audit)."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+    }, async ({ fact_id, reason, workspace_id }) => {
         const guard = requireReady();
         if (guard)
             return guard;
         const now = nowISO();
         try {
+            const scope = resolveScope(workspace_id);
+            const existing = await getPointForWorkspaceWrite(fact_id, scope);
+            if (existing.error) {
+                return { content: [{ type: "text", text: JSON.stringify(existing.error, null, 2) }], isError: true };
+            }
+            const redactedReason = redactStorageText(reason);
             await qdrantSetPayload([fact_id], {
-                superseded_by: `forgotten:${reason}`,
+                superseded_by: `forgotten:${redactedReason.text}`,
                 superseded_at: now,
                 updated_at: now,
             });
-            return { content: [{ type: "text", text: JSON.stringify({ status: "forgotten", fact_id, reason }) }] };
+            return { content: [{ type: "text", text: JSON.stringify({
+                            status: "forgotten",
+                            fact_id,
+                            reason: redactedReason.text,
+                            ...(redactedReason.redacted ? { redaction: redactedReason } : {}),
+                        }) }] };
         }
         catch (e) {
             return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }] };
         }
     });
     // ── memory_verify ───────────────────────────────────────────────────────
-    mcp.tool("memory_verify", "Confirm a fact is still accurate. Resets the staleness clock and bumps verification count.", {
-        fact_id: z.string().describe("ID of the fact to verify"),
-    }, async ({ fact_id }) => {
+    mcp.tool("memory_verify", [
+        "Confirm an existing fact is still accurate, without re-storing it. Resets the staleness clock and bumps a verification counter.",
+        "Use this when memory_heartbeat surfaces a stale fact ID and you can confirm it's still true (e.g. you just observed the system in that state). Lighter than memory_store(supersedes:) — same content, fresh timestamp.",
+        "If the fact is no longer true, use memory_forget or memory_store(supersedes:) instead.",
+    ].join(" "), {
+        fact_id: z.string().describe("ID of the fact to verify (from memory_recall or memory_heartbeat)."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+    }, async ({ fact_id, workspace_id }) => {
         const guard = requireReady();
         if (guard)
             return guard;
         const now = nowISO();
         try {
-            const existing = await qdrantGetPoints([fact_id]).catch(() => null);
+            const scope = resolveScope(workspace_id);
+            const writable = await getPointForWorkspaceWrite(fact_id, scope);
+            if (writable.error) {
+                return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
+            }
             let currentCount = 0;
-            const existingPt = existing?.result?.[0];
+            const existingPt = writable.point;
             if (existingPt) {
                 currentCount = existingPt.payload.verification_count ?? 0;
             }
@@ -649,24 +844,26 @@ export function registerTools(mcp) {
         }
     });
     // ── memory_review ───────────────────────────────────────────────────────
-    mcp.tool("memory_review", "Review recent daemon-extracted facts. Supports approve (verify), reject (forget), or correct (supersede with edited text).", {
-        limit: z.number().optional().default(10).describe("Max facts to return (default 10)"),
-        action: z.enum(["list", "approve", "reject", "correct"]).optional().default("list")
-            .describe("Action: list, approve, reject, correct"),
-        fact_id: z.string().optional().describe("Fact ID (required for approve/reject/correct)"),
-        reason: z.string().optional().describe("Reason for rejection"),
-        corrected_content: z.string().optional().describe("Corrected fact text (for correct action)"),
-    }, async ({ limit, action, fact_id, reason, corrected_content }) => {
+    mcp.tool("memory_review", [
+        "Triage facts that were extracted automatically by the bikky daemon (source='daemon').",
+        "Only useful when the daemon is running and capturing memories from logs/transcripts; otherwise this returns an empty list. Supports four actions: list (default — show recent daemon facts), approve (mark verified), reject (mark superseded with reason), correct (replace with edited content as a new fact).",
+    ].join(" "), {
+        limit: z.number().optional().default(10).describe("Max facts to return when action=list (default 10)."),
+        action: z.enum(["list", "approve", "reject", "correct"]).optional().default("list").describe("What to do. list = show recent daemon-extracted facts (default). approve = confirm a fact is correct (bumps verification count). reject = mark a fact as wrong (requires 'reason'). correct = supersede with an edited version (requires 'corrected_content')."),
+        fact_id: z.string().optional().describe("Fact ID to act on. Required for approve / reject / correct."),
+        reason: z.string().optional().describe("Required for action=reject. Short reason the fact is wrong."),
+        corrected_content: z.string().optional().describe("Required for action=correct. The fixed fact text. Stored as a new fact that supersedes the original."),
+        workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
+        include_legacy_workspace: z.boolean().optional().describe("Backwards-compatibility: also include legacy facts with no workspace_id. Default false."),
+    }, async ({ limit, action, fact_id, reason, corrected_content, workspace_id, include_legacy_workspace }) => {
         const guard = requireReady();
         if (guard)
             return guard;
+        const scope = resolveScope(workspace_id, include_legacy_workspace);
         if (action === "list") {
-            const result = await qdrantScroll({
-                must: [
-                    { key: "source", match: { value: "daemon" } },
-                    { is_null: { key: "superseded_by" } },
-                ],
-            }, (limit ?? 10) * 2);
+            const filter = scopedFilter(scope) ?? { must: [] };
+            filter.must.push({ key: "source", match: { value: "daemon" } });
+            const result = await qdrantScroll(filter, (limit ?? 10) * 2);
             const points = (result.result?.points ?? [])
                 .sort((a, b) => (b.payload.created_at ?? "").localeCompare(a.payload.created_at ?? ""))
                 .slice(0, limit ?? 10);
@@ -684,9 +881,12 @@ export function registerTools(mcp) {
         }
         const now = nowISO();
         if (action === "approve") {
-            const existing = await qdrantGetPoints([fact_id]).catch(() => null);
+            const writable = await getPointForWorkspaceWrite(fact_id, scope);
+            if (writable.error) {
+                return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
+            }
             let currentCount = 0;
-            const approvePt = existing?.result?.[0];
+            const approvePt = writable.point;
             if (approvePt) {
                 currentCount = approvePt.payload.verification_count ?? 0;
             }
@@ -701,28 +901,52 @@ export function registerTools(mcp) {
             if (!reason) {
                 return { content: [{ type: "text", text: "Error: reason is required for reject action." }] };
             }
+            const writable = await getPointForWorkspaceWrite(fact_id, scope);
+            if (writable.error) {
+                return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
+            }
+            const redactedReason = redactStorageText(reason);
             await qdrantSetPayload([fact_id], {
-                superseded_by: `rejected:${reason}`,
+                superseded_by: `rejected:${redactedReason.text}`,
                 superseded_at: now,
                 updated_at: now,
             });
-            return { content: [{ type: "text", text: JSON.stringify({ status: "rejected", fact_id, reason }) }] };
+            return { content: [{ type: "text", text: JSON.stringify({
+                            status: "rejected",
+                            fact_id,
+                            reason: redactedReason.text,
+                            ...(redactedReason.redacted ? { redaction: redactedReason } : {}),
+                        }) }] };
         }
         if (action === "correct") {
             if (!corrected_content) {
                 return { content: [{ type: "text", text: "Error: corrected_content is required for correct action." }] };
             }
-            const original = await qdrantGetPoints([fact_id]).catch(() => null);
-            const origPayload = original?.result?.[0]?.payload;
-            const vector = await embed(corrected_content);
+            const writable = await getPointForWorkspaceWrite(fact_id, scope);
+            if (writable.error) {
+                return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
+            }
+            const origPayload = writable.point?.payload;
+            const redactedCorrected = redactStorageText(corrected_content);
+            const correctionScope = origPayload?.workspace_id
+                ? resolveScope(origPayload.workspace_id, false)
+                : scope;
+            const vector = await embed(redactedCorrected.text);
             const correctedId = crypto.randomUUID();
-            const origCategory = origPayload?.category ?? "observation";
-            const hash = contentHash(origCategory, corrected_content);
-            await qdrantUpsert(correctedId, vector, {
-                content: corrected_content,
+            const origCategory = normalizeCategory(origPayload?.category ?? DEFAULT_CATEGORY);
+            const hash = contentHash(origCategory, redactedCorrected.text);
+            const correctedPayload = {
+                content: redactedCorrected.text,
                 category: origCategory,
-                domain: origPayload?.domain ?? "work",
-                kind: origPayload?.kind ?? "fact",
+                domain: normalizeDomain(origPayload?.domain ?? DEFAULT_DOMAIN),
+                kind: normalizeKind(origPayload?.kind ?? "fact"),
+                ...(origPayload?.memory_subtype ? { memory_subtype: origPayload.memory_subtype } : {}),
+                ...(origPayload?.layer ? { layer: origPayload.layer } : {}),
+                ...(origPayload?.episode_id ? { episode_id: origPayload.episode_id } : {}),
+                ...(origPayload?.workstream_key ? { workstream_key: origPayload.workstream_key } : {}),
+                ...(origPayload?.task_key ? { task_key: origPayload.task_key } : {}),
+                ...(origPayload?.repo ? { repo: origPayload.repo } : {}),
+                ...(origPayload?.branch ? { branch: origPayload.branch } : {}),
                 entities: origPayload?.entities ?? [],
                 source: "user",
                 confidence: 0.95,
@@ -735,7 +959,10 @@ export function registerTools(mcp) {
                 created_at: now,
                 updated_at: now,
                 metadata: { ...(origPayload?.metadata ?? {}), corrected_from: fact_id },
-            });
+            };
+            addWorkspacePayload(correctedPayload, correctionScope);
+            addRedactionPayload(correctedPayload, redactedCorrected);
+            await qdrantUpsert(correctedId, vector, correctedPayload);
             await qdrantSetPayload([fact_id], {
                 superseded_by: correctedId,
                 superseded_at: now,
@@ -745,177 +972,11 @@ export function registerTools(mcp) {
         }
         return { content: [{ type: "text", text: `Unknown action: ${String(action)}` }] };
     });
-    // ── memory_session_summary ──────────────────────────────────────────────
-    mcp.tool("memory_session_summary", "Store a compressed summary of the current session. Call before a session ends or when a major task completes. " +
-        "Future sessions receive this via memory_recall('session briefing'). Idempotent per session_id.", {
-        session_id: z.string().describe("Session UUID"),
-        summary: z.string().describe("2-5 sentence compressed summary of what happened this session"),
-        tasks_completed: z.array(z.string()).optional().default([]).describe("Task slugs completed"),
-        decisions_made: z.array(z.string()).optional().default([]).describe("Key decisions"),
-        entities_touched: z.array(z.string()).optional().default([]).describe("Entities involved (lowercase)"),
-    }, async ({ session_id, summary, tasks_completed, decisions_made, entities_touched }) => {
-        const guard = requireReady();
-        if (guard)
-            return guard;
-        const now = nowISO();
-        const normalizedEntities = entities_touched.map((e) => e.toLowerCase());
-        // Check for existing summary for this session
-        try {
-            const existing = await qdrantScroll({ must: [
-                    { key: "session_id", match: { value: session_id } },
-                    { key: "kind", match: { value: "summary" } },
-                    { is_null: { key: "superseded_by" } },
-                ] }, 1);
-            const summaryPoint = existing.result?.points?.[0];
-            if (summaryPoint) {
-                const point = summaryPoint;
-                const vector = await embed(summary);
-                await qdrantUpsert(point.id, vector, {
-                    ...point.payload,
-                    content: summary,
-                    kind: "summary",
-                    domain: "work",
-                    source: "system",
-                    tasks_completed,
-                    decisions_made,
-                    entities: normalizedEntities,
-                    content_hash: contentHash("observation", summary),
-                    updated_at: now,
-                });
-                return {
-                    content: [{ type: "text", text: JSON.stringify({
-                                action: "updated", fact_id: point.id, session_id,
-                            }) }],
-                };
-            }
-        }
-        catch (e) {
-            log("WARN", `Session summary lookup failed: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        // Insert new summary
-        const vector = await embed(summary);
-        const factId = newId();
-        await qdrantUpsert(factId, vector, {
-            content: summary,
-            category: "observation",
-            domain: "work",
-            kind: "summary",
-            entities: normalizedEntities,
-            source: "system",
-            confidence: 1.0,
-            content_hash: contentHash("observation", summary),
-            reinforcement_count: 1,
-            last_reinforced_at: now,
-            superseded_by: null,
-            superseded_at: null,
-            created_at: now,
-            updated_at: now,
-            session_id,
-            tasks_completed,
-            decisions_made,
-        });
-        return {
-            content: [{ type: "text", text: JSON.stringify({
-                        action: "stored", fact_id: factId, session_id,
-                    }) }],
-        };
-    });
-    // ── memory_distill ──────────────────────────────────────────────────────
-    mcp.tool("memory_distill", "Consolidate recent session summaries into distilled patterns. Call when 5+ session summaries exist. " +
-        "Uses LLM to extract recurring patterns and key learnings, then supersedes the source summaries.", {
-        days: z.number().optional().default(14).describe("Look-back period in days (default 14)"),
-        max_summaries: z.number().optional().default(20).describe("Max summaries to consolidate"),
-    }, async ({ days, max_summaries }) => {
-        const guard = requireReady();
-        if (guard)
-            return guard;
-        const now = nowISO();
-        const daysVal = days ?? 14;
-        const maxVal = max_summaries ?? 20;
-        const since = new Date(Date.now() - daysVal * 86400000).toISOString();
-        const summaryResults = await qdrantScroll({ must: [
-                { key: "kind", match: { value: "summary" } },
-                { key: "created_at", range: { gte: since } },
-                { is_null: { key: "superseded_by" } },
-            ] }, maxVal);
-        const summaries = summaryResults.result?.points ?? [];
-        if (summaries.length < 3) {
-            return {
-                content: [{ type: "text", text: JSON.stringify({
-                            action: "skipped",
-                            reason: `Only ${summaries.length} session summaries in the last ${daysVal} days. Need at least 3.`,
-                        }) }],
-            };
-        }
-        const summaryTexts = summaries.map((s, i) => {
-            const p = s.payload;
-            const parts = [`Session ${i + 1} (${p.created_at}):\n${p.content}`];
-            if (p.tasks_completed?.length)
-                parts.push(`Tasks: ${p.tasks_completed.join(", ")}`);
-            if (p.decisions_made?.length)
-                parts.push(`Decisions: ${p.decisions_made.join("; ")}`);
-            return parts.join("\n");
-        }).join("\n\n---\n\n");
-        const systemPrompt = "You are a memory consolidation system. Given session summaries from an engineering agent, " +
-            "extract recurring patterns, consolidated learnings, and key facts. Output:\n" +
-            "1. Recurring patterns (things that keep coming up)\n" +
-            "2. Key infrastructure/project facts learned\n" +
-            "3. Decisions made and their rationale\n" +
-            "4. Open issues or recurring problems\n" +
-            "Be concise — one line per point. Omit ephemeral details.";
-        let distilledContent;
-        try {
-            distilledContent = await chatComplete(systemPrompt, summaryTexts);
-        }
-        catch (e) {
-            return { content: [{ type: "text", text: `Distillation failed: ${e instanceof Error ? e.message : String(e)}` }] };
-        }
-        const allEntities = [...new Set(summaries.flatMap((s) => s.payload.entities ?? []))];
-        const vector = await embed(distilledContent);
-        const factId = newId();
-        const sourceIds = summaries.map((s) => s.id);
-        await qdrantUpsert(factId, vector, {
-            content: distilledContent,
-            category: "observation",
-            domain: "work",
-            kind: "distilled",
-            entities: allEntities,
-            source: "system",
-            confidence: 0.9,
-            content_hash: contentHash("observation", distilledContent),
-            reinforcement_count: 1,
-            last_reinforced_at: now,
-            superseded_by: null,
-            superseded_at: null,
-            created_at: now,
-            updated_at: now,
-            distilled_from: sourceIds,
-            distilled_period_start: since,
-            distilled_period_end: now,
-            summary_count: summaries.length,
-        });
-        try {
-            await qdrantSetPayload(sourceIds, {
-                superseded_by: factId,
-                superseded_at: now,
-            });
-        }
-        catch (e) {
-            log("WARN", `Failed to supersede some source summaries: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify({
-                        action: "distilled",
-                        fact_id: factId,
-                        summaries_consolidated: summaries.length,
-                        period: { start: since, end: now },
-                        entities: allEntities,
-                        preview: distilledContent.substring(0, 300) + (distilledContent.length > 300 ? "..." : ""),
-                    }, null, 2) }],
-        };
-    });
     // ── memory_heartbeat ────────────────────────────────────────────────────
-    mcp.tool("memory_heartbeat", "Lightweight reflection check. Returns memory nudge (if no stores in 10+ min), staleness alerts (every 3rd call), and reflection prompt.", {}, async () => {
+    mcp.tool("memory_heartbeat", [
+        "Reflection check-in. Returns up to three things: a memory nudge if you haven't stored anything in 10+ minutes, stale-fact alerts every 3rd call (with IDs you can pass to memory_verify or memory_forget), and a reflection prompt asking whether the last few minutes of work produced anything worth storing.",
+        "Call periodically during interactive sessions — roughly every 10 minutes or every 3rd user prompt. No arguments. Cheap and read-only.",
+    ].join(" "), {}, async () => {
         heartbeatCount++;
         const sections = [];
         const nudge = buildMemoryNudge();
@@ -924,17 +985,17 @@ export function registerTools(mcp) {
         if (heartbeatCount % 3 === 0 && ready) {
             try {
                 const staleThreshold = new Date(Date.now() - STALENESS_DAYS * 86400000).toISOString();
-                const staleResults = await qdrantScroll({ must: [
-                        { key: "category", match: { any: ["infrastructure", "projects", "decisions"] } },
-                        { is_null: { key: "superseded_by" } },
-                    ],
-                    should: [
-                        { key: "last_reinforced_at", range: { lte: staleThreshold } },
-                        { is_null: { key: "last_reinforced_at" } },
-                    ],
-                    must_not: [
-                        { key: "last_verified_at", range: { gte: staleThreshold } },
-                    ] }, 3);
+                const scope = resolveScope();
+                const staleFilter = scopedFilter(scope) ?? { must: [] };
+                staleFilter.must.push({ key: "category", match: { any: ["infrastructure", "projects", "decisions"] } });
+                staleFilter.should = [
+                    { key: "last_reinforced_at", range: { lte: staleThreshold } },
+                    { is_null: { key: "last_reinforced_at" } },
+                ];
+                staleFilter.must_not = [
+                    { key: "last_verified_at", range: { gte: staleThreshold } },
+                ];
+                const staleResults = await qdrantScroll(staleFilter, 3);
                 const staleFacts = staleResults.result?.points ?? [];
                 if (staleFacts.length > 0) {
                     const staleLines = staleFacts.map((f) => {
@@ -950,8 +1011,12 @@ export function registerTools(mcp) {
                 log("WARN", `Staleness check failed: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
-        sections.push("🔍 **Reflect:** What have you learned, decided, or discovered since the last heartbeat? " +
-            "If anything is worth persisting for future sessions, call memory_store now.");
+        sections.push("🔍 Reflect: think about the LAST 10 minutes of work and answer in your head:\n" +
+            "  1. Did you touch a service, port, config, or file path you hadn't seen before?\n" +
+            "  2. Did you make a choice (library, pattern, approach) you'd want a future session to know about?\n" +
+            "  3. Did you hit an error and find a workaround?\n" +
+            "  4. Did the user state a preference or constraint?\n" +
+            "If any answer is yes, call memory_store now — one atomic fact per item, with category/domain/entities.");
         return { content: [{ type: "text", text: sections.join("\n\n") }] };
     });
 }