bikky 0.3.7 → 0.3.9

package/dist/mcp/tools.js

@@ -4,16 +4,19 @@
 import crypto from "node:crypto";
 import { z } from "zod";
 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 { contentHash, daysSince, lastActivityDate, computeCombinedScore, buildFilter, formatFact, structuredFact, 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, EXTRACTION_HEALTH_PATH } from "../config.js";
 import { existsSync, readFileSync } from "node:fs";
 import { inspectWatcherPaths, formatIssue, repairSuspiciousWatcherPaths } from "../daemon/watcher-health.js";
+import { normalizeActorId, resolveActorIdentity } from "../provenance/actor.js";
 import { addRedactionPayload, combineRedactions, redactStorageText, } from "../privacy/redaction.js";
 // ---------------------------------------------------------------------------
 // Runtime state
 // ---------------------------------------------------------------------------
 const NUDGE_INTERVAL_MS = 10 * 60 * 1000;
+const MEMORY_RECALL_DEFAULT_LIMIT = 10;
+const MEMORY_RECALL_MAX_LIMIT = 50;
 let lastStoreTime = Date.now();
 let heartbeatCount = 0;
 // ---------------------------------------------------------------------------
@@ -25,9 +28,10 @@ function nowISO() {
 function newId() {
     return crypto.randomUUID();
 }
-function resolveScope(workspaceId, includeLegacyWorkspace = false) {
+function resolveScope(workspaceId, includeLegacyWorkspace = false, actorId) {
     return {
         workspaceId: workspaceId?.trim() || undefined,
+        actorId: normalizeActorId(actorId),
         includeLegacy: includeLegacyWorkspace,
     };
 }
@@ -38,11 +42,21 @@ function scopedFilter(scope, extra = {}) {
         includeLegacyWorkspace: scope.includeLegacy,
     });
 }
-function addWorkspacePayload(payload, scope) {
+function addWorkspacePayload(payload, scope, actor) {
     if (scope.workspaceId)
         payload["workspace_id"] = scope.workspaceId;
-    if (scope.actorId)
-        payload["actor_id"] = scope.actorId;
+    const actorId = actor?.actor_id ?? scope.actorId;
+    if (actorId)
+        payload["actor_id"] = actorId;
+    if (actor?.actor_label) {
+        const metadata = payload["metadata"] && typeof payload["metadata"] === "object" && !Array.isArray(payload["metadata"])
+            ? payload["metadata"]
+            : {};
+        metadata["actor_label"] = actor.actor_label;
+        if (actor.source)
+            metadata["actor_source"] = actor.source;
+        payload["metadata"] = metadata;
+    }
 }
 async function getPointForWorkspaceWrite(factId, _scope) {
     const existing = await qdrantGetPoints([factId]);
@@ -88,12 +102,19 @@ function buildMemoryNudge() {
     // session typically produces. The agent picks the best fit.
     return `🧠 Memory nudge: No memory_store calls in ${mins} minutes. ` +
         "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" +
+        "  • engineering — codebase maps, architecture, infra, ops, troubleshooting?\n" +
+        "  • product — requirements, decisions, workflows, roadmap, metrics, market insight?\n" +
+        "  • human — preferences, owners, working agreements, durable activity events?\n" +
+        "  • system — session, episode, workstream, or quality-rollup memory?\n" +
         "If yes, call memory_store now so future sessions inherit the knowledge.";
 }
+function clampRecallLimit(limit) {
+    const rawLimit = limit ?? MEMORY_RECALL_DEFAULT_LIMIT;
+    const integerLimit = Math.trunc(rawLimit);
+    if (!Number.isFinite(integerLimit))
+        return MEMORY_RECALL_DEFAULT_LIMIT;
+    return Math.min(Math.max(integerLimit, 1), MEMORY_RECALL_MAX_LIMIT);
+}
 /**
  * Entity-graph traversal for memory_recall.
  */
@@ -108,7 +129,7 @@ async function graphTraversal(primaryResults, limit, scope) {
             }
         }
         if (primaryEntities.size === 0)
-            return [];
+            return { points: [] };
         const relatedEntities = new Set();
         for (const entity of primaryEntities) {
             const outgoingFilter = scopedFilter(scope, { excludeKinds: MEMORY_RECALL_EXCLUDED_KINDS }) ?? { must: [] };
@@ -129,7 +150,7 @@ async function graphTraversal(primaryResults, limit, scope) {
         for (const e of primaryEntities)
             relatedEntities.delete(e);
         if (relatedEntities.size === 0)
-            return [];
+            return { points: [] };
         const relatedFacts = [];
         const maxPerEntity = Math.max(2, Math.floor(limit / relatedEntities.size));
         for (const entity of relatedEntities) {
@@ -144,12 +165,10 @@ async function graphTraversal(primaryResults, limit, scope) {
             if (relatedFacts.length >= limit)
                 break;
         }
-        return relatedFacts
-            .slice(0, Math.ceil(limit / 2))
-            .map((r) => formatFact(r));
+        return { points: relatedFacts.slice(0, Math.ceil(limit / 2)) };
     }
     catch (e) {
-        return [`(graph traversal failed: ${e instanceof Error ? e.message : String(e)})`];
+        return { points: [], error: e instanceof Error ? e.message : String(e) };
     }
 }
 // ---------------------------------------------------------------------------
@@ -328,7 +347,7 @@ export function registerTools(mcp) {
     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'.",
+        "Dedup is automatic (content hash + vector similarity), so you do NOT need to recall first for deduplication. Recall first only when you intentionally need broader context to decide whether a new fact supersedes an older one. 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(" "), {
@@ -339,6 +358,7 @@ export function registerTools(mcp) {
         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."),
+        actor_id: z.string().optional().describe("Stable actor/person/agent identity associated with this capture. Overrides identity config/env/Git-derived fallback for this write."),
         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)."),
@@ -355,13 +375,14 @@ export function registerTools(mcp) {
             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, }) => {
+    }, async ({ content, category, entities, domain, kind, memory_subtype, workspace_id, actor_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 scope = resolveScope(workspace_id);
+        const actor = resolveActorIdentity({ actorId: actor_id, config: loadConfig() });
         const normalizedKind = normalizeKind(kind);
         let normalizedSubtype = null;
         try {
@@ -545,13 +566,13 @@ export function registerTools(mcp) {
             payload["repo"] = repo;
         if (branch)
             payload["branch"] = branch;
-        if (review_status)
-            payload["review_status"] = review_status;
-        addWorkspacePayload(payload, scope);
-        addRedactionPayload(payload, factRedactionSummary);
         if (metadata && Object.keys(metadata).length > 0) {
             payload["metadata"] = metadata;
         }
+        if (review_status)
+            payload["review_status"] = review_status;
+        addWorkspacePayload(payload, scope, actor);
+        addRedactionPayload(payload, factRedactionSummary);
         await qdrantUpsert(factId, vector, payload);
         // 7. Insert relation point if provided
         let relationId = null;
@@ -579,7 +600,7 @@ export function registerTools(mcp) {
                 relation_type: sanitizedRelation.type.toLowerCase(),
                 to_entity: sanitizedRelation.to.toLowerCase(),
             };
-            addWorkspacePayload(relPayload, scope);
+            addWorkspacePayload(relPayload, scope, actor);
             addRedactionPayload(relPayload, relationRedactionSummary);
             await qdrantUpsert(relationId, relVector, relPayload);
         }
@@ -588,6 +609,8 @@ export function registerTools(mcp) {
             fact_id: factId,
             workspace_id: scope.workspaceId,
         };
+        if (actor.actor_id)
+            result["actor_id"] = actor.actor_id;
         if (relationId)
             result["relation_id"] = relationId;
         if (redactionSummary.redacted)
@@ -608,9 +631,10 @@ export function registerTools(mcp) {
         "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.",
+        "  3. Conflict/replacement check — recall similar facts when you suspect new information may supersede an older fact. Deduplication during memory_store is automatic.",
         "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.",
+        `By default output is human-readable text. Use output_format=json for machine-parseable results with separate results and related arrays. Default limit is ${MEMORY_RECALL_DEFAULT_LIMIT}; maximum effective limit is ${MEMORY_RECALL_MAX_LIMIT}.`,
     ].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."),
@@ -618,6 +642,7 @@ export function registerTools(mcp) {
         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."),
+        actor_id: z.string().optional().describe("Filter to facts captured by or associated with this stable actor identity. Optional."),
         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."),
@@ -628,15 +653,18 @@ export function registerTools(mcp) {
         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?')."),
+        limit: z.number().optional().default(MEMORY_RECALL_DEFAULT_LIMIT).describe(`Max primary results to return (default ${MEMORY_RECALL_DEFAULT_LIMIT}, maximum ${MEMORY_RECALL_MAX_LIMIT}). Values above the maximum are clamped.`),
+        graph_depth: z.number().optional().default(0).describe("Entity-graph traversal depth. 0 = vector search only (fast, default). 1 = also surface up to ceil(limit / 2) extra 1-hop entity-related facts (slower; use when the user asks 'what's connected to X?'). In JSON output these are returned separately as related."),
+        output_format: z.enum(["text", "json"]).optional().default("text").describe("Response format. text = backward-compatible human-readable lines (default). json = parseable object with query, limit metadata, results, related, counts, and optional nudge."),
         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, }) => {
+    }, async ({ query, category, domain, kind, memory_subtype, workspace_id, actor_id, include_legacy_workspace, entity, episode_id, workstream_key, task_key, repo, branch, review_status, since, until, limit, graph_depth, output_format, metadata_filter, }) => {
         const guard = requireReady();
         if (guard)
             return guard;
-        const requestedLimit = limit ?? 10;
-        const scope = resolveScope(workspace_id, include_legacy_workspace);
+        const requestedLimit = limit ?? MEMORY_RECALL_DEFAULT_LIMIT;
+        const effectiveLimit = clampRecallLimit(limit);
+        const actorFilter = resolveActorIdentity({ actorId: actor_id, useGitFallback: false });
+        const scope = resolveScope(workspace_id, include_legacy_workspace, actorFilter.actor_id);
         const redactedQuery = redactStorageText(query);
         const vector = await embed(redactedQuery.text);
         const normalizedKind = kind ? normalizeKind(kind) : undefined;
@@ -669,27 +697,64 @@ export function registerTools(mcp) {
             metadata: metadata_filter,
             excludeKinds: MEMORY_RECALL_EXCLUDED_KINDS,
         });
-        const results = await qdrantSearch(vector, filter, requestedLimit * 2);
+        const results = await qdrantSearch(vector, filter, effectiveLimit * 2);
         if (!results.result?.length) {
             const nudge = buildMemoryNudge();
+            if (output_format === "json") {
+                return { content: [{ type: "text", text: JSON.stringify({
+                                query: redactedQuery.text,
+                                requested_limit: requestedLimit,
+                                effective_limit: effectiveLimit,
+                                max_limit: MEMORY_RECALL_MAX_LIMIT,
+                                limit_clamped: effectiveLimit !== requestedLimit,
+                                graph_depth: graph_depth ?? 0,
+                                result_count: 0,
+                                related_count: 0,
+                                results: [],
+                                related: [],
+                                ...(nudge ? { nudge } : {}),
+                                ...(redactedQuery.redacted ? { query_redaction: redactedQuery } : {}),
+                            }, null, 2) }] };
+            }
             const text = nudge ? `No matching facts found.\n\n${nudge}` : "No matching facts found.";
             return { content: [{ type: "text", text }] };
         }
         const ranked = results.result
             .map((r) => ({ ...r, _combinedScore: computeCombinedScore(r) }))
             .sort((a, b) => b._combinedScore - a._combinedScore)
-            .slice(0, requestedLimit);
+            .slice(0, effectiveLimit);
         const lines = ranked.map((r) => formatFact(r));
+        let related = { points: [] };
         if ((graph_depth ?? 0) >= 1) {
-            const relatedLines = await graphTraversal(ranked, requestedLimit, scope);
-            if (relatedLines.length > 0) {
+            related = await graphTraversal(ranked, effectiveLimit, scope);
+            if (related.points.length > 0) {
                 lines.push("", "── Related (1-hop) ──");
-                lines.push(...relatedLines);
+                lines.push(...related.points.map((r) => formatFact(r)));
+            }
+            else if (related.error) {
+                lines.push("", `(graph traversal failed: ${related.error})`);
             }
         }
         const nudge = buildMemoryNudge();
         if (nudge)
             lines.push("", nudge);
+        if (output_format === "json") {
+            return { content: [{ type: "text", text: JSON.stringify({
+                            query: redactedQuery.text,
+                            requested_limit: requestedLimit,
+                            effective_limit: effectiveLimit,
+                            max_limit: MEMORY_RECALL_MAX_LIMIT,
+                            limit_clamped: effectiveLimit !== requestedLimit,
+                            graph_depth: graph_depth ?? 0,
+                            result_count: ranked.length,
+                            related_count: related.points.length,
+                            results: ranked.map((r) => structuredFact(r)),
+                            related: related.points.map((r) => structuredFact(r)),
+                            ...(related.error ? { graph_error: related.error } : {}),
+                            ...(nudge ? { nudge } : {}),
+                            ...(redactedQuery.redacted ? { query_redaction: redactedQuery } : {}),
+                        }, null, 2) }] };
+        }
         return { content: [{ type: "text", text: lines.join("\n") }] };
     });
     // ── memory_entity ───────────────────────────────────────────────────────
@@ -839,6 +904,7 @@ export function registerTools(mcp) {
         const now = nowISO();
         try {
             const scope = resolveScope(workspace_id);
+            const _actor = resolveActorIdentity({ config: loadConfig() });
             const existing = await getPointForWorkspaceWrite(fact_id, scope);
             if (existing.error) {
                 return { content: [{ type: "text", text: JSON.stringify(existing.error, null, 2) }], isError: true };
@@ -882,6 +948,7 @@ export function registerTools(mcp) {
         const now = nowISO();
         try {
             const scope = resolveScope(workspace_id);
+            const _actor = resolveActorIdentity({ config: loadConfig() });
             const writable = await getPointForWorkspaceWrite(fact_id, scope);
             if (writable.error) {
                 return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
@@ -927,6 +994,7 @@ export function registerTools(mcp) {
         const now = nowISO();
         try {
             const scope = resolveScope(workspace_id);
+            const actor = resolveActorIdentity({ config: loadConfig() });
             const writable = await getPointForWorkspaceWrite(fact_id, scope);
             if (writable.error) {
                 return { content: [{ type: "text", text: JSON.stringify(writable.error, null, 2) }], isError: true };
@@ -948,7 +1016,7 @@ export function registerTools(mcp) {
             const redactedEvent = redactStorageText(eventContent);
             const eventPayload = {
                 content: redactedEvent.text,
-                category: "observations",
+                category: categoryForMemorySubtype("feedback_event") ?? "system",
                 domain: "software_engineering",
                 kind: "telemetry",
                 memory_subtype: "feedback_event",
@@ -963,7 +1031,7 @@ export function registerTools(mcp) {
                 created_at: now,
                 updated_at: now,
             };
-            addWorkspacePayload(eventPayload, scope);
+            addWorkspacePayload(eventPayload, scope, actor);
             addRedactionPayload(eventPayload, redactedEvent);
             try {
                 const eventVector = await embed(redactedEvent.text);
@@ -1002,6 +1070,7 @@ export function registerTools(mcp) {
         const now = nowISO();
         try {
             const scope = resolveScope(workspace_id);
+            const actor = resolveActorIdentity({ config: loadConfig() });
             const target = await getPointForWorkspaceWrite(fact_id, scope);
             if (target.error) {
                 return { content: [{ type: "text", text: JSON.stringify(target.error, null, 2) }], isError: true };
@@ -1013,7 +1082,7 @@ export function registerTools(mcp) {
             const redactedEvent = redactStorageText(eventContent);
             const eventPayload = {
                 content: redactedEvent.text,
-                category: "observations",
+                category: categoryForMemorySubtype("outcome_event") ?? "system",
                 domain: "software_engineering",
                 kind: "telemetry",
                 memory_subtype: "outcome_event",
@@ -1028,7 +1097,7 @@ export function registerTools(mcp) {
                 created_at: now,
                 updated_at: now,
             };
-            addWorkspacePayload(eventPayload, scope);
+            addWorkspacePayload(eventPayload, scope, actor);
             addRedactionPayload(eventPayload, redactedEvent);
             const eventVector = await embed(redactedEvent.text);
             await qdrantUpsert(eventId, eventVector, eventPayload);
@@ -1058,7 +1127,8 @@ export function registerTools(mcp) {
         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 summary relates to."),
         workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
-    }, async ({ content, entities, episode_id, workstream_key, task_key, repo, workspace_id }) => {
+        actor_id: z.string().optional().describe("Stable actor identity associated with this session summary. Overrides identity config/env/Git fallback."),
+    }, async ({ content, entities, episode_id, workstream_key, task_key, repo, workspace_id, actor_id }) => {
         const guard = requireReady();
         if (guard)
             return guard;
@@ -1066,13 +1136,14 @@ export function registerTools(mcp) {
         const now = nowISO();
         try {
             const scope = resolveScope(workspace_id);
+            const actor = resolveActorIdentity({ actorId: actor_id, config: loadConfig() });
             const normalizedEntities = (entities ?? []).map((e) => e.trim().toLowerCase()).filter(Boolean);
             const summaryId = newId();
             const redactedContent = redactStorageText(content);
             const vector = await embed(redactedContent.text);
             const payload = {
                 content: redactedContent.text,
-                category: categoryForMemorySubtype("session_index") ?? "projects",
+                category: categoryForMemorySubtype("session_index") ?? "system",
                 domain: "software_engineering",
                 kind: "summary",
                 memory_subtype: "session_index",
@@ -1097,7 +1168,7 @@ export function registerTools(mcp) {
                 payload["task_key"] = task_key;
             if (repo)
                 payload["repo"] = repo;
-            addWorkspacePayload(payload, scope);
+            addWorkspacePayload(payload, scope, actor);
             addRedactionPayload(payload, redactedContent);
             await qdrantUpsert(summaryId, vector, payload);
             return {
@@ -1105,6 +1176,7 @@ export function registerTools(mcp) {
                             status: "summary_stored",
                             summary_id: summaryId,
                             workspace_id: scope.workspaceId,
+                            actor_id: actor.actor_id,
                         }) }],
             };
         }
@@ -1124,7 +1196,8 @@ export function registerTools(mcp) {
         task_key: z.string().optional().describe("Task or issue key associated with this learning, if relevant."),
         repo: z.string().optional().describe("Repository or project surface this learning applies to."),
         workspace_id: z.string().optional().describe("Workspace namespace. Omit to use the default from config."),
-    }, async ({ content, entities, supersedes, task_key, repo, workspace_id }) => {
+        actor_id: z.string().optional().describe("Stable actor identity associated with this distillation. Overrides identity config/env/Git fallback."),
+    }, async ({ content, entities, supersedes, task_key, repo, workspace_id, actor_id }) => {
         const guard = requireReady();
         if (guard)
             return guard;
@@ -1132,6 +1205,7 @@ export function registerTools(mcp) {
         const now = nowISO();
         try {
             const scope = resolveScope(workspace_id);
+            const actor = resolveActorIdentity({ actorId: actor_id, config: loadConfig() });
             const normalizedEntities = entities.map((e) => e.trim().toLowerCase()).filter(Boolean);
             const distilledId = newId();
             const redactedContent = redactStorageText(content);
@@ -1148,7 +1222,7 @@ export function registerTools(mcp) {
             }
             const payload = {
                 content: redactedContent.text,
-                category: categoryForMemorySubtype("convention") ?? "observations",
+                category: categoryForMemorySubtype("convention") ?? "engineering",
                 domain: "software_engineering",
                 kind: "distilled",
                 memory_subtype: "convention",
@@ -1169,7 +1243,7 @@ export function registerTools(mcp) {
                 payload["task_key"] = task_key;
             if (repo)
                 payload["repo"] = repo;
-            addWorkspacePayload(payload, scope);
+            addWorkspacePayload(payload, scope, actor);
             addRedactionPayload(payload, redactedContent);
             await qdrantUpsert(distilledId, vector, payload);
             return {
@@ -1178,6 +1252,7 @@ export function registerTools(mcp) {
                             distilled_id: distilledId,
                             supersedes: supersedes ?? null,
                             workspace_id: scope.workspaceId,
+                            actor_id: actor.actor_id,
                         }) }],
             };
         }
@@ -1187,11 +1262,11 @@ export function registerTools(mcp) {
     });
     // ── memory_review ───────────────────────────────────────────────────────
     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).",
+        "Triage facts that were captured automatically by Bikky (source='system').",
+        "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 system-captured 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')."),
+        action: z.enum(["list", "approve", "reject", "correct"]).optional().default("list").describe("What to do. list = show recent system-captured 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."),
@@ -1204,13 +1279,13 @@ export function registerTools(mcp) {
         const scope = resolveScope(workspace_id, include_legacy_workspace);
         if (action === "list") {
             const filter = scopedFilter(scope) ?? { must: [] };
-            filter.must.push({ key: "source", match: { value: "daemon" } });
+            filter.must.push({ key: "source", match: { any: ["system", "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);
             if (points.length === 0) {
-                return { content: [{ type: "text", text: "No daemon-extracted facts found." }] };
+                return { content: [{ type: "text", text: "No system-captured facts found." }] };
             }
             const lines = points.map((pt) => {
                 const p = pt.payload;
@@ -1273,6 +1348,7 @@ export function registerTools(mcp) {
             const correctionScope = origPayload?.workspace_id
                 ? resolveScope(origPayload.workspace_id, false)
                 : scope;
+            const actor = resolveActorIdentity({ config: loadConfig() });
             const vector = await embed(redactedCorrected.text);
             const correctedId = crypto.randomUUID();
             const origCategory = normalizeCategory(origPayload?.category ?? DEFAULT_CATEGORY);
@@ -1302,7 +1378,7 @@ export function registerTools(mcp) {
                 updated_at: now,
                 metadata: { ...(origPayload?.metadata ?? {}), corrected_from: fact_id },
             };
-            addWorkspacePayload(correctedPayload, correctionScope);
+            addWorkspacePayload(correctedPayload, correctionScope, actor);
             addRedactionPayload(correctedPayload, redactedCorrected);
             await qdrantUpsert(correctedId, vector, correctedPayload);
             await qdrantSetPayload([fact_id], {
@@ -1329,7 +1405,7 @@ export function registerTools(mcp) {
                 const staleThreshold = new Date(Date.now() - STALENESS_DAYS * 86400000).toISOString();
                 const scope = resolveScope();
                 const staleFilter = scopedFilter(scope) ?? { must: [] };
-                staleFilter.must.push({ key: "category", match: { any: ["infrastructure", "projects", "decisions"] } });
+                staleFilter.must.push({ key: "category", match: { any: ["engineering", "product", "human", "system"] } });
                 staleFilter.should = [
                     { key: "last_reinforced_at", range: { lte: staleThreshold } },
                     { is_null: { key: "last_reinforced_at" } },
@@ -1354,10 +1430,10 @@ export function registerTools(mcp) {
             }
         }
         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" +
+            "  1. Did you touch engineering context: code, infra, ops, access, troubleshooting, or conventions?\n" +
+            "  2. Did you capture product context: a requirement, decision, workflow, roadmap item, metric, or market insight?\n" +
+            "  3. Did you learn human context: a preference, owner, working agreement, person profile, or durable activity event?\n" +
+            "  4. Did the work produce system context: session, episode, workstream, recall, feedback, outcome, or rollup state?\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") }] };
     });