bikky 0.3.1 → 0.3.2

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, domainValues, kindValues, memorySubtypeValues, sourceValues, 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);
@@ -139,13 +177,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 +197,18 @@ 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"),
+        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 +230,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 +247,14 @@ 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 () => {
         const results = { qdrant: false, embedding: false, collection: false };
-        if (qdrantUrl && qdrantApiKey) {
+        if (qdrantUrl) {
             try {
                 await qdrantReq("GET", "/collections");
                 results["qdrant"] = true;
@@ -246,12 +285,23 @@ export function registerTools(mcp) {
         "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"),
+            .describe("Subject matter: codebase, infrastructure, operations, decisions, product_domain, projects, people, preferences, observations"),
         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"),
+            .describe("Activity profile — e.g. software_engineering, product_strategy, business_operations, research, personal_productivity"),
         kind: z.enum(kindValues()).default(DEFAULT_KIND)
             .describe("Knowledge form — fact, summary, distilled, relation"),
+        memory_subtype: z.enum(memorySubtypeValues()).optional()
+            .describe("Optional subtype within kind, such as codebase_map, episode, workstream, convention, or recall_event"),
+        workspace_id: z.string().optional()
+            .describe("Optional workspace namespace for team memory."),
+        episode_id: z.string().optional().describe("Optional coherent episode identifier"),
+        workstream_key: z.string().optional().describe("Optional durable workstream key"),
+        task_key: z.string().optional().describe("Optional task or issue key"),
+        repo: z.string().optional().describe("Optional repository or project surface"),
+        branch: z.string().optional().describe("Optional branch or working surface"),
+        review_status: z.enum(["candidate", "reviewed", "approved", "rejected"]).optional()
+            .describe("Optional review lifecycle status"),
         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)"),
@@ -264,20 +314,54 @@ export function registerTools(mcp) {
         }).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 }) => {
+    }, 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 +385,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 +451,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 +466,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 +482,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 +528,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) {
@@ -447,22 +560,63 @@ export function registerTools(mcp) {
         "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)"),
+        domain: z.string().optional().describe("Filter by domain activity profile"),
         kind: z.string().optional().describe("Filter by kind (fact, summary, distilled, relation)"),
+        memory_subtype: z.string().optional().describe("Filter by memory subtype"),
+        workspace_id: z.string().optional().describe("Filter by optional workspace namespace."),
+        include_legacy_workspace: z.boolean().optional()
+            .describe("Include legacy facts without workspace_id in this workspace query."),
         entity: z.string().optional().describe("Filter by entity name"),
+        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"),
         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 }) => {
+    }, 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 +629,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);
@@ -490,25 +644,24 @@ export function registerTools(mcp) {
     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 }) => {
+        workspace_id: z.string().optional().describe("Filter by optional workspace namespace."),
+        include_legacy_workspace: z.boolean().optional()
+            .describe("Include legacy facts without workspace_id in this workspace query."),
+    }, 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) {
@@ -548,17 +701,19 @@ export function registerTools(mcp) {
         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 }) => {
+        workspace_id: z.string().optional().describe("Filter by optional workspace namespace."),
+        include_legacy_workspace: z.boolean().optional()
+            .describe("Include legacy facts without workspace_id in this workspace query."),
+    }, 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 +721,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() } });
             }
@@ -596,18 +749,30 @@ export function registerTools(mcp) {
     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 }) => {
+        workspace_id: z.string().optional().describe("Optional workspace namespace."),
+    }, 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)}` }] };
@@ -616,15 +781,20 @@ export function registerTools(mcp) {
     // ── 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 }) => {
+        workspace_id: z.string().optional().describe("Optional workspace namespace."),
+    }, 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;
             }
@@ -656,17 +826,18 @@ export function registerTools(mcp) {
         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 }) => {
+        workspace_id: z.string().optional().describe("Filter by optional workspace namespace."),
+        include_legacy_workspace: z.boolean().optional()
+            .describe("Include legacy facts without workspace_id in this workspace query."),
+    }, 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 +855,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 +875,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 +933,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,175 +946,6 @@ 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 () => {
         heartbeatCount++;
@@ -924,17 +956,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 +982,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") }] };
     });
 }