@graphorin/memory 0.5.0

package/dist/tools/fact-tools.d.ts

@@ -0,0 +1,294 @@
+import { MemoryToolDeps } from "./types.js";
+import { Tool } from "@graphorin/core";
+import { z } from "zod";
+
+//#region src/tools/fact-tools.d.ts
+declare const factRememberInputSchema: z.ZodObject<{
+  text: z.ZodString;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+  confidence: z.ZodOptional<z.ZodNumber>;
+  sensitivity: z.ZodOptional<z.ZodEnum<["public", "internal", "secret"]>>;
+  validFrom: z.ZodOptional<z.ZodString>;
+  validTo: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  text: string;
+  sensitivity?: "public" | "internal" | "secret" | undefined;
+  tags?: string[] | undefined;
+  confidence?: number | undefined;
+  validFrom?: string | undefined;
+  validTo?: string | undefined;
+}, {
+  text: string;
+  sensitivity?: "public" | "internal" | "secret" | undefined;
+  tags?: string[] | undefined;
+  confidence?: number | undefined;
+  validFrom?: string | undefined;
+  validTo?: string | undefined;
+}>;
+declare const factRememberOutputSchema: z.ZodObject<{
+  factId: z.ZodString;
+  /**
+   * MRET-3: `true` when the write landed in quarantine (hidden from
+   * default recall until validated). A synthesized consolidator write or
+   * a candidate that tripped the injection heuristics quarantines.
+   */
+  quarantined: z.ZodBoolean;
+  /** Why it was quarantined, when it was. */
+  quarantineReason: z.ZodOptional<z.ZodEnum<["injection", "synthesized"]>>;
+}, "strip", z.ZodTypeAny, {
+  factId: string;
+  quarantined: boolean;
+  quarantineReason?: "injection" | "synthesized" | undefined;
+}, {
+  factId: string;
+  quarantined: boolean;
+  quarantineReason?: "injection" | "synthesized" | undefined;
+}>;
+type FactRememberInput = z.infer<typeof factRememberInputSchema>;
+type FactRememberOutput = z.infer<typeof factRememberOutputSchema>;
+declare const factSearchInputSchema: z.ZodObject<{
+  query: z.ZodString;
+  topK: z.ZodOptional<z.ZodNumber>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+  asOf: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  query: string;
+  topK?: number | undefined;
+  asOf?: string | undefined;
+  tags?: string[] | undefined;
+}, {
+  query: string;
+  topK?: number | undefined;
+  asOf?: string | undefined;
+  tags?: string[] | undefined;
+}>;
+declare const factSearchOutputSchema: z.ZodObject<{
+  hits: z.ZodArray<z.ZodObject<{
+    factId: z.ZodString;
+    text: z.ZodString;
+    score: z.ZodNumber;
+    sensitivity: z.ZodEnum<["public", "internal", "secret"]>;
+    provenance: z.ZodOptional<z.ZodEnum<["user", "tool", "extraction", "reflection", "induction", "imported"]>>;
+  }, "strip", z.ZodTypeAny, {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+  }, {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  hits: {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+  }[];
+}, {
+  hits: {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: "user" | "tool" | "extraction" | "reflection" | "induction" | "imported" | undefined;
+  }[];
+}>;
+type FactSearchInput = z.infer<typeof factSearchInputSchema>;
+type FactSearchOutput = z.infer<typeof factSearchOutputSchema>;
+declare const factSupersedeInputSchema: z.ZodObject<{
+  oldId: z.ZodString;
+  newText: z.ZodString;
+  reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  newText: string;
+  oldId: string;
+  reason?: string | undefined;
+}, {
+  newText: string;
+  oldId: string;
+  reason?: string | undefined;
+}>;
+declare const factSupersedeOutputSchema: z.ZodObject<{
+  oldId: z.ZodString;
+  newId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  oldId: string;
+  newId: string;
+}, {
+  oldId: string;
+  newId: string;
+}>;
+type FactSupersedeInput = z.infer<typeof factSupersedeInputSchema>;
+type FactSupersedeOutput = z.infer<typeof factSupersedeOutputSchema>;
+declare const factForgetInputSchema: z.ZodObject<{
+  factId: z.ZodString;
+  reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  factId: string;
+  reason?: string | undefined;
+}, {
+  factId: string;
+  reason?: string | undefined;
+}>;
+declare const factForgetOutputSchema: z.ZodObject<{
+  factId: z.ZodString;
+  forgotten: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+  factId: string;
+  forgotten: boolean;
+}, {
+  factId: string;
+  forgotten: boolean;
+}>;
+type FactForgetInput = z.infer<typeof factForgetInputSchema>;
+type FactForgetOutput = z.infer<typeof factForgetOutputSchema>;
+declare const factHistoryInputSchema: z.ZodObject<{
+  factId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+  factId: string;
+}, {
+  factId: string;
+}>;
+declare const factHistoryOutputSchema: z.ZodObject<{
+  chain: z.ZodArray<z.ZodObject<{
+    factId: z.ZodString;
+    text: z.ZodString;
+    validFrom: z.ZodOptional<z.ZodString>;
+    validTo: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodString>;
+    supersededBy: z.ZodOptional<z.ZodString>;
+    sensitivity: z.ZodEnum<["public", "internal", "secret"]>;
+  }, "strip", z.ZodTypeAny, {
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    validFrom?: string | undefined;
+    validTo?: string | undefined;
+    supersedes?: string | undefined;
+    supersededBy?: string | undefined;
+  }, {
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    validFrom?: string | undefined;
+    validTo?: string | undefined;
+    supersedes?: string | undefined;
+    supersededBy?: string | undefined;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  chain: {
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    validFrom?: string | undefined;
+    validTo?: string | undefined;
+    supersedes?: string | undefined;
+    supersededBy?: string | undefined;
+  }[];
+}, {
+  chain: {
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    validFrom?: string | undefined;
+    validTo?: string | undefined;
+    supersedes?: string | undefined;
+    supersededBy?: string | undefined;
+  }[];
+}>;
+type FactHistoryInput = z.infer<typeof factHistoryInputSchema>;
+type FactHistoryOutput = z.infer<typeof factHistoryOutputSchema>;
+declare const factValidateInputSchema: z.ZodObject<{
+  factId: z.ZodString;
+  reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  factId: string;
+  reason?: string | undefined;
+}, {
+  factId: string;
+  reason?: string | undefined;
+}>;
+declare const factValidateOutputSchema: z.ZodObject<{
+  factId: z.ZodString;
+  validated: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+  factId: string;
+  validated: boolean;
+}, {
+  factId: string;
+  validated: boolean;
+}>;
+type FactValidateInput = z.infer<typeof factValidateInputSchema>;
+type FactValidateOutput = z.infer<typeof factValidateOutputSchema>;
+/**
+ * `fact_remember` — persist a single semantic fact. The minimum-viable
+ * pipeline writes the fact straight through with MD5 deduplication;
+ * Phase 10b extends the body with the multi-stage conflict resolution.
+ *
+ * @stable
+ */
+declare function createFactRememberTool(deps: MemoryToolDeps): Tool<FactRememberInput, FactRememberOutput>;
+/**
+ * `fact_search` — hybrid (vector + FTS5) search over the user's
+ * semantic memory. Results merged through the configured reranker.
+ *
+ * @stable
+ */
+declare function createFactSearchTool(deps: MemoryToolDeps): Tool<FactSearchInput, FactSearchOutput>;
+/**
+ * `fact_supersede` — soft-supersede an old fact by storing a new one
+ * that replaces it. The old fact is kept for replay but ranked below
+ * the new one.
+ *
+ * @stable
+ */
+declare function createFactSupersedeTool(deps: MemoryToolDeps): Tool<FactSupersedeInput, FactSupersedeOutput>;
+/**
+ * `fact_forget` — soft-delete a fact (kept for replay; never hard-
+ * deleted at this layer).
+ *
+ * @stable
+ */
+declare function createFactForgetTool(deps: MemoryToolDeps): Tool<FactForgetInput, FactForgetOutput>;
+/**
+ * `fact_history` — trace how a fact changed over time. Returns the
+ * full bi-temporal supersede chain the given fact belongs to, oldest →
+ * newest, including superseded entries, so the agent can answer "what
+ * did the user say before" / "how did this change". Read-only. P0-2.
+ *
+ * @stable
+ */
+declare function createFactHistoryTool(deps: MemoryToolDeps): Tool<FactHistoryInput, FactHistoryOutput>;
+/**
+ * `fact_validate` — promote a quarantined fact to active (P1-4). The
+ * validation path that admits a synthesized (consolidator / reflection)
+ * memory into action-driving recall once it has been reviewed; the
+ * promotion is audited in `memory_history`.
+ *
+ * MRET-3 / MST-1 — two gates close the one-turn memory-poisoning chain
+ * (`fact_remember(poison)` → `fact_validate(id)` → active recall):
+ *
+ * 1. `needsApproval: true` — the run suspends for a human decision
+ *    before this tool ever executes, so the agent cannot silently
+ *    promote any quarantined fact.
+ * 2. The underlying `SemanticMemory.validate(...)` re-checks the fact's
+ *    text against the injection heuristics and **refuses** (no `force`
+ *    is passed here) — an injection-flagged memory cannot be promoted by
+ *    the agent at all. Only an operator, via the programmatic API with
+ *    `{ force: true }`, can override after review.
+ *
+ * Synthesized-but-clean consolidator writes promote normally once
+ * approved.
+ *
+ * @stable
+ */
+declare function createFactValidateTool(deps: MemoryToolDeps): Tool<FactValidateInput, FactValidateOutput>;
+//#endregion
+export { createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool };
+//# sourceMappingURL=fact-tools.d.ts.map

package/dist/tools/fact-tools.d.ts.map

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

package/dist/tools/fact-tools.js

@@ -0,0 +1,293 @@
+import { tool } from "@graphorin/tools";
+import { z } from "zod";
+
+//#region src/tools/fact-tools.ts
+const sensitivityEnum = z.enum([
+	"public",
+	"internal",
+	"secret"
+]);
+const provenanceEnum = z.enum([
+	"user",
+	"tool",
+	"extraction",
+	"reflection",
+	"induction",
+	"imported"
+]);
+const factRememberInputSchema = z.object({
+	text: z.string().min(1).max(8192),
+	tags: z.array(z.string().min(1).max(64)).max(32).optional(),
+	confidence: z.number().min(0).max(1).optional(),
+	sensitivity: sensitivityEnum.optional(),
+	validFrom: z.string().datetime().optional(),
+	validTo: z.string().datetime().optional()
+});
+const factRememberOutputSchema = z.object({
+	factId: z.string(),
+	quarantined: z.boolean(),
+	quarantineReason: z.enum(["injection", "synthesized"]).optional()
+});
+const factSearchInputSchema = z.object({
+	query: z.string().min(1).max(1024),
+	topK: z.number().int().positive().max(50).optional(),
+	tags: z.array(z.string().min(1)).max(16).optional(),
+	asOf: z.string().datetime().optional()
+});
+const factSearchOutputSchema = z.object({ hits: z.array(z.object({
+	factId: z.string(),
+	text: z.string(),
+	score: z.number(),
+	sensitivity: sensitivityEnum,
+	provenance: provenanceEnum.optional()
+})) });
+const factSupersedeInputSchema = z.object({
+	oldId: z.string().min(1),
+	newText: z.string().min(1).max(8192),
+	reason: z.string().max(512).optional()
+});
+const factSupersedeOutputSchema = z.object({
+	oldId: z.string(),
+	newId: z.string()
+});
+const factForgetInputSchema = z.object({
+	factId: z.string().min(1),
+	reason: z.string().max(512).optional()
+});
+const factForgetOutputSchema = z.object({
+	factId: z.string(),
+	forgotten: z.boolean()
+});
+const factHistoryInputSchema = z.object({ factId: z.string().min(1) });
+const factHistoryOutputSchema = z.object({ chain: z.array(z.object({
+	factId: z.string(),
+	text: z.string(),
+	validFrom: z.string().optional(),
+	validTo: z.string().optional(),
+	supersedes: z.string().optional(),
+	supersededBy: z.string().optional(),
+	sensitivity: sensitivityEnum
+})) });
+const factValidateInputSchema = z.object({
+	factId: z.string().min(1),
+	reason: z.string().max(512).optional()
+});
+const factValidateOutputSchema = z.object({
+	factId: z.string(),
+	validated: z.boolean()
+});
+/**
+* `fact_remember` — persist a single semantic fact. The minimum-viable
+* pipeline writes the fact straight through with MD5 deduplication;
+* Phase 10b extends the body with the multi-stage conflict resolution.
+*
+* @stable
+*/
+function createFactRememberTool(deps) {
+	return tool({
+		name: "fact_remember",
+		description: "Persist an atomic factual statement about the user, the world, or the current session. Prefer one fact per call; the system applies dedup + conflict resolution downstream. Pass `validFrom` / `validTo` for bi-temporal facts and `sensitivity` to control redaction.",
+		inputSchema: factRememberInputSchema,
+		outputSchema: factRememberOutputSchema,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: ["memory", "semantic"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const outcome = await deps.semantic.rememberWithDecision(scope, {
+				text: input.text,
+				...input.tags !== void 0 ? { tags: input.tags } : {},
+				...input.confidence !== void 0 ? { confidence: input.confidence } : {},
+				...input.sensitivity !== void 0 ? { sensitivity: input.sensitivity } : {},
+				...input.validFrom !== void 0 ? { validFrom: input.validFrom } : {},
+				...input.validTo !== void 0 ? { validTo: input.validTo } : {}
+			});
+			return {
+				factId: outcome.fact.id,
+				quarantined: outcome.fact.status === "quarantined",
+				...outcome.quarantineReason !== void 0 ? { quarantineReason: outcome.quarantineReason } : {}
+			};
+		}
+	});
+}
+/**
+* `fact_search` — hybrid (vector + FTS5) search over the user's
+* semantic memory. Results merged through the configured reranker.
+*
+* @stable
+*/
+function createFactSearchTool(deps) {
+	return tool({
+		name: "fact_search",
+		description: "Search the user's long-term factual memory by natural-language query. Returns up to `topK` matched facts with their score and sensitivity. Use this BEFORE asking the user a question they may have answered earlier. Pass `asOf` (ISO-8601) to read memory as it was at a past instant — point-in-time / 'what was true on date X' — instead of the current state.",
+		inputSchema: factSearchInputSchema,
+		outputSchema: factSearchOutputSchema,
+		sideEffectClass: "read-only",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "pure",
+		tags: ["memory", "semantic"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			return { hits: (await deps.semantic.search(scope, input.query, {
+				...input.topK !== void 0 ? { topK: input.topK } : {},
+				...input.tags !== void 0 && input.tags.length > 0 ? { tags: input.tags } : {},
+				...input.asOf !== void 0 ? { asOf: input.asOf } : {},
+				signal: ctx.signal
+			})).map((hit) => ({
+				factId: hit.record.id,
+				text: hit.record.text,
+				score: hit.score,
+				sensitivity: hit.record.sensitivity,
+				...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {}
+			})) };
+		}
+	});
+}
+/**
+* `fact_supersede` — soft-supersede an old fact by storing a new one
+* that replaces it. The old fact is kept for replay but ranked below
+* the new one.
+*
+* @stable
+*/
+function createFactSupersedeTool(deps) {
+	return tool({
+		name: "fact_supersede",
+		description: "Mark an old fact superseded by a new one. Use this when the user's situation changed (moved cities, updated a goal, switched a preference) — the old fact is preserved for replay but no longer surfaced as current.",
+		inputSchema: factSupersedeInputSchema,
+		outputSchema: factSupersedeOutputSchema,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: ["memory", "semantic"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const result = await deps.semantic.supersede(scope, input.oldId, { text: input.newText }, input.reason);
+			return {
+				oldId: result.old,
+				newId: result.new.id
+			};
+		}
+	});
+}
+/**
+* `fact_forget` — soft-delete a fact (kept for replay; never hard-
+* deleted at this layer).
+*
+* @stable
+*/
+function createFactForgetTool(deps) {
+	return tool({
+		name: "fact_forget",
+		description: "Soft-delete a fact. The record is preserved for replay but no longer surfaced by fact_search. Use only for explicit user-driven removal (privacy / user request).",
+		inputSchema: factForgetInputSchema,
+		outputSchema: factForgetOutputSchema,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: ["memory", "semantic"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			await deps.semantic.forget(scope, input.factId, input.reason);
+			return {
+				factId: input.factId,
+				forgotten: true
+			};
+		}
+	});
+}
+/**
+* `fact_history` — trace how a fact changed over time. Returns the
+* full bi-temporal supersede chain the given fact belongs to, oldest →
+* newest, including superseded entries, so the agent can answer "what
+* did the user say before" / "how did this change". Read-only. P0-2.
+*
+* @stable
+*/
+function createFactHistoryTool(deps) {
+	return tool({
+		name: "fact_history",
+		description: "Trace how a fact changed over time. Given a factId, returns its full bi-temporal supersede chain (oldest → newest), including superseded entries, with each entry's validFrom/validTo. Use this to answer 'how did this change' or 'what was the previous value'.",
+		inputSchema: factHistoryInputSchema,
+		outputSchema: factHistoryOutputSchema,
+		sideEffectClass: "read-only",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "pure",
+		tags: [
+			"memory",
+			"semantic",
+			"temporal"
+		],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			return { chain: (await deps.semantic.history(scope, input.factId)).map((f) => ({
+				factId: f.id,
+				text: f.text,
+				...f.validFrom !== void 0 ? { validFrom: f.validFrom } : {},
+				...f.validTo !== void 0 ? { validTo: f.validTo } : {},
+				...f.supersedes !== void 0 ? { supersedes: f.supersedes } : {},
+				...f.supersededBy !== void 0 ? { supersededBy: f.supersededBy } : {},
+				sensitivity: f.sensitivity
+			})) };
+		}
+	});
+}
+/**
+* `fact_validate` — promote a quarantined fact to active (P1-4). The
+* validation path that admits a synthesized (consolidator / reflection)
+* memory into action-driving recall once it has been reviewed; the
+* promotion is audited in `memory_history`.
+*
+* MRET-3 / MST-1 — two gates close the one-turn memory-poisoning chain
+* (`fact_remember(poison)` → `fact_validate(id)` → active recall):
+*
+* 1. `needsApproval: true` — the run suspends for a human decision
+*    before this tool ever executes, so the agent cannot silently
+*    promote any quarantined fact.
+* 2. The underlying `SemanticMemory.validate(...)` re-checks the fact's
+*    text against the injection heuristics and **refuses** (no `force`
+*    is passed here) — an injection-flagged memory cannot be promoted by
+*    the agent at all. Only an operator, via the programmatic API with
+*    `{ force: true }`, can override after review.
+*
+* Synthesized-but-clean consolidator writes promote normally once
+* approved.
+*
+* @stable
+*/
+function createFactValidateTool(deps) {
+	return tool({
+		name: "fact_validate",
+		description: "Promote a quarantined fact to active so it becomes eligible for normal recall. Quarantined facts are memories the system synthesized or flagged as risky; validating one is a deliberate, human-approved admission and never a routine step. This action requires approval, and facts flagged as prompt-injection cannot be promoted here — they are an operator-only decision.",
+		inputSchema: factValidateInputSchema,
+		outputSchema: factValidateOutputSchema,
+		needsApproval: true,
+		sideEffectClass: "side-effecting",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "memory-aware",
+		tags: [
+			"memory",
+			"semantic",
+			"safety"
+		],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			await deps.semantic.validate(scope, input.factId, input.reason);
+			return {
+				factId: input.factId,
+				validated: true
+			};
+		}
+	});
+}
+
+//#endregion
+export { createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool };
+//# sourceMappingURL=fact-tools.js.map

package/dist/tools/fact-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-tools.js","names":[],"sources":["../../src/tools/fact-tools.ts"],"sourcesContent":["import type { Tool } from '@graphorin/core';\nimport { tool } from '@graphorin/tools';\nimport { z } from 'zod';\nimport type { MemoryToolDeps } from './types.js';\n\nconst sensitivityEnum = z.enum(['public', 'internal', 'secret']);\nconst provenanceEnum = z.enum([\n  'user',\n  'tool',\n  'extraction',\n  'reflection',\n  'induction',\n  'imported',\n]);\n\nconst factRememberInputSchema = z.object({\n  text: z.string().min(1).max(8192),\n  tags: z.array(z.string().min(1).max(64)).max(32).optional(),\n  confidence: z.number().min(0).max(1).optional(),\n  sensitivity: sensitivityEnum.optional(),\n  validFrom: z.string().datetime().optional(),\n  validTo: z.string().datetime().optional(),\n});\nconst factRememberOutputSchema = z.object({\n  factId: z.string(),\n  /**\n   * MRET-3: `true` when the write landed in quarantine (hidden from\n   * default recall until validated). A synthesized consolidator write or\n   * a candidate that tripped the injection heuristics quarantines.\n   */\n  quarantined: z.boolean(),\n  /** Why it was quarantined, when it was. */\n  quarantineReason: z.enum(['injection', 'synthesized']).optional(),\n});\n\ntype FactRememberInput = z.infer<typeof factRememberInputSchema>;\ntype FactRememberOutput = z.infer<typeof factRememberOutputSchema>;\n\nconst factSearchInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(50).optional(),\n  tags: z.array(z.string().min(1)).max(16).optional(),\n  asOf: z.string().datetime().optional(),\n});\nconst factSearchOutputSchema = z.object({\n  hits: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      score: z.number(),\n      sensitivity: sensitivityEnum,\n      provenance: provenanceEnum.optional(),\n    }),\n  ),\n});\n\ntype FactSearchInput = z.infer<typeof factSearchInputSchema>;\ntype FactSearchOutput = z.infer<typeof factSearchOutputSchema>;\n\nconst factSupersedeInputSchema = z.object({\n  oldId: z.string().min(1),\n  newText: z.string().min(1).max(8192),\n  reason: z.string().max(512).optional(),\n});\nconst factSupersedeOutputSchema = z.object({\n  oldId: z.string(),\n  newId: z.string(),\n});\n\ntype FactSupersedeInput = z.infer<typeof factSupersedeInputSchema>;\ntype FactSupersedeOutput = z.infer<typeof factSupersedeOutputSchema>;\n\nconst factForgetInputSchema = z.object({\n  factId: z.string().min(1),\n  reason: z.string().max(512).optional(),\n});\nconst factForgetOutputSchema = z.object({\n  factId: z.string(),\n  forgotten: z.boolean(),\n});\n\ntype FactForgetInput = z.infer<typeof factForgetInputSchema>;\ntype FactForgetOutput = z.infer<typeof factForgetOutputSchema>;\n\nconst factHistoryInputSchema = z.object({\n  factId: z.string().min(1),\n});\nconst factHistoryOutputSchema = z.object({\n  chain: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      validFrom: z.string().optional(),\n      validTo: z.string().optional(),\n      supersedes: z.string().optional(),\n      supersededBy: z.string().optional(),\n      sensitivity: sensitivityEnum,\n    }),\n  ),\n});\n\ntype FactHistoryInput = z.infer<typeof factHistoryInputSchema>;\ntype FactHistoryOutput = z.infer<typeof factHistoryOutputSchema>;\n\nconst factValidateInputSchema = z.object({\n  factId: z.string().min(1),\n  reason: z.string().max(512).optional(),\n});\nconst factValidateOutputSchema = z.object({\n  factId: z.string(),\n  validated: z.boolean(),\n});\n\ntype FactValidateInput = z.infer<typeof factValidateInputSchema>;\ntype FactValidateOutput = z.infer<typeof factValidateOutputSchema>;\n\n/**\n * `fact_remember` — persist a single semantic fact. The minimum-viable\n * pipeline writes the fact straight through with MD5 deduplication;\n * Phase 10b extends the body with the multi-stage conflict resolution.\n *\n * @stable\n */\nexport function createFactRememberTool(\n  deps: MemoryToolDeps,\n): Tool<FactRememberInput, FactRememberOutput> {\n  return tool<FactRememberInput, FactRememberOutput>({\n    name: 'fact_remember',\n    description:\n      'Persist an atomic factual statement about the user, the world, or the current session. Prefer one fact per call; the system applies dedup + conflict resolution downstream. Pass `validFrom` / `validTo` for bi-temporal facts and `sensitivity` to control redaction.',\n    inputSchema: factRememberInputSchema,\n    outputSchema: factRememberOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const outcome = await deps.semantic.rememberWithDecision(scope, {\n        text: input.text,\n        ...(input.tags !== undefined ? { tags: input.tags } : {}),\n        ...(input.confidence !== undefined ? { confidence: input.confidence } : {}),\n        ...(input.sensitivity !== undefined ? { sensitivity: input.sensitivity } : {}),\n        ...(input.validFrom !== undefined ? { validFrom: input.validFrom } : {}),\n        ...(input.validTo !== undefined ? { validTo: input.validTo } : {}),\n      });\n      // MRET-3: tell the caller when the write was quarantined so a\n      // poisoned fact cannot masquerade as a normally-stored one.\n      return {\n        factId: outcome.fact.id,\n        quarantined: outcome.fact.status === 'quarantined',\n        ...(outcome.quarantineReason !== undefined\n          ? { quarantineReason: outcome.quarantineReason }\n          : {}),\n      };\n    },\n  });\n}\n\n/**\n * `fact_search` — hybrid (vector + FTS5) search over the user's\n * semantic memory. Results merged through the configured reranker.\n *\n * @stable\n */\nexport function createFactSearchTool(\n  deps: MemoryToolDeps,\n): Tool<FactSearchInput, FactSearchOutput> {\n  return tool<FactSearchInput, FactSearchOutput>({\n    name: 'fact_search',\n    description:\n      \"Search the user's long-term factual memory by natural-language query. Returns up to `topK` matched facts with their score and sensitivity. Use this BEFORE asking the user a question they may have answered earlier. Pass `asOf` (ISO-8601) to read memory as it was at a past instant — point-in-time / 'what was true on date X' — instead of the current state.\",\n    inputSchema: factSearchInputSchema,\n    outputSchema: factSearchOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const hits = await deps.semantic.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        // MRET-4: forward the tags filter — it was accepted by the\n        // schema and silently dropped here.\n        ...(input.tags !== undefined && input.tags.length > 0 ? { tags: input.tags } : {}),\n        ...(input.asOf !== undefined ? { asOf: input.asOf } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        hits: hits.map((hit) => ({\n          factId: hit.record.id,\n          text: hit.record.text,\n          score: hit.score,\n          sensitivity: hit.record.sensitivity,\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `fact_supersede` — soft-supersede an old fact by storing a new one\n * that replaces it. The old fact is kept for replay but ranked below\n * the new one.\n *\n * @stable\n */\nexport function createFactSupersedeTool(\n  deps: MemoryToolDeps,\n): Tool<FactSupersedeInput, FactSupersedeOutput> {\n  return tool<FactSupersedeInput, FactSupersedeOutput>({\n    name: 'fact_supersede',\n    description:\n      \"Mark an old fact superseded by a new one. Use this when the user's situation changed (moved cities, updated a goal, switched a preference) — the old fact is preserved for replay but no longer surfaced as current.\",\n    inputSchema: factSupersedeInputSchema,\n    outputSchema: factSupersedeOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const result = await deps.semantic.supersede(\n        scope,\n        input.oldId,\n        { text: input.newText },\n        input.reason,\n      );\n      return { oldId: result.old, newId: result.new.id };\n    },\n  });\n}\n\n/**\n * `fact_forget` — soft-delete a fact (kept for replay; never hard-\n * deleted at this layer).\n *\n * @stable\n */\nexport function createFactForgetTool(\n  deps: MemoryToolDeps,\n): Tool<FactForgetInput, FactForgetOutput> {\n  return tool<FactForgetInput, FactForgetOutput>({\n    name: 'fact_forget',\n    description:\n      'Soft-delete a fact. The record is preserved for replay but no longer surfaced by fact_search. Use only for explicit user-driven removal (privacy / user request).',\n    inputSchema: factForgetInputSchema,\n    outputSchema: factForgetOutputSchema,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      await deps.semantic.forget(scope, input.factId, input.reason);\n      return { factId: input.factId, forgotten: true };\n    },\n  });\n}\n\n/**\n * `fact_history` — trace how a fact changed over time. Returns the\n * full bi-temporal supersede chain the given fact belongs to, oldest →\n * newest, including superseded entries, so the agent can answer \"what\n * did the user say before\" / \"how did this change\". Read-only. P0-2.\n *\n * @stable\n */\nexport function createFactHistoryTool(\n  deps: MemoryToolDeps,\n): Tool<FactHistoryInput, FactHistoryOutput> {\n  return tool<FactHistoryInput, FactHistoryOutput>({\n    name: 'fact_history',\n    description:\n      \"Trace how a fact changed over time. Given a factId, returns its full bi-temporal supersede chain (oldest → newest), including superseded entries, with each entry's validFrom/validTo. Use this to answer 'how did this change' or 'what was the previous value'.\",\n    inputSchema: factHistoryInputSchema,\n    outputSchema: factHistoryOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'semantic', 'temporal'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const chain = await deps.semantic.history(scope, input.factId);\n      return {\n        chain: chain.map((f) => ({\n          factId: f.id,\n          text: f.text,\n          ...(f.validFrom !== undefined ? { validFrom: f.validFrom } : {}),\n          ...(f.validTo !== undefined ? { validTo: f.validTo } : {}),\n          ...(f.supersedes !== undefined ? { supersedes: f.supersedes } : {}),\n          ...(f.supersededBy !== undefined ? { supersededBy: f.supersededBy } : {}),\n          sensitivity: f.sensitivity,\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `fact_validate` — promote a quarantined fact to active (P1-4). The\n * validation path that admits a synthesized (consolidator / reflection)\n * memory into action-driving recall once it has been reviewed; the\n * promotion is audited in `memory_history`.\n *\n * MRET-3 / MST-1 — two gates close the one-turn memory-poisoning chain\n * (`fact_remember(poison)` → `fact_validate(id)` → active recall):\n *\n * 1. `needsApproval: true` — the run suspends for a human decision\n *    before this tool ever executes, so the agent cannot silently\n *    promote any quarantined fact.\n * 2. The underlying `SemanticMemory.validate(...)` re-checks the fact's\n *    text against the injection heuristics and **refuses** (no `force`\n *    is passed here) — an injection-flagged memory cannot be promoted by\n *    the agent at all. Only an operator, via the programmatic API with\n *    `{ force: true }`, can override after review.\n *\n * Synthesized-but-clean consolidator writes promote normally once\n * approved.\n *\n * @stable\n */\nexport function createFactValidateTool(\n  deps: MemoryToolDeps,\n): Tool<FactValidateInput, FactValidateOutput> {\n  return tool<FactValidateInput, FactValidateOutput>({\n    name: 'fact_validate',\n    description:\n      'Promote a quarantined fact to active so it becomes eligible for normal recall. Quarantined facts are memories the system synthesized or flagged as risky; validating one is a deliberate, human-approved admission and never a routine step. This action requires approval, and facts flagged as prompt-injection cannot be promoted here — they are an operator-only decision.',\n    inputSchema: factValidateInputSchema,\n    outputSchema: factValidateOutputSchema,\n    // MRET-3: the only real gate on a model-callable tool — suspend the\n    // run for a human decision before promoting anything out of quarantine.\n    needsApproval: true,\n    sideEffectClass: 'side-effecting',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'memory-aware',\n    tags: ['memory', 'semantic', 'safety'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      // No `force`: the agent path can never promote an injection-flagged\n      // fact (validate throws QuarantinePromotionRefusedError for those).\n      await deps.semantic.validate(scope, input.factId, input.reason);\n      return { factId: input.factId, validated: true };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,35 @@
+import { MemoryToolDeps, ScopeResolver } from "./types.js";
+import { createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool } from "./block-tools.js";
+import { createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool } from "./fact-tools.js";
+import { createConversationSearchTool, createDeepRecallTool, createRecallEpisodesTool } from "./recall-tools.js";
+import { Tool } from "@graphorin/core";
+
+//#region src/tools/index.d.ts
+
+/**
+ * Options for {@link buildMemoryTools}.
+ *
+ * @stable
+ */
+interface BuildMemoryToolsOptions {
+  /**
+   * Append the gated `deep_recall` tool (P2-4) as a twelfth tool. The
+   * facade sets this only when `iterativeRetrieval` is configured, so the
+   * default tool surface stays at the canonical eleven. Default `false`.
+   */
+  readonly includeDeepRecall?: boolean;
+}
+/**
+ * Build the canonical eleven-memory-tool array. Order is stable —
+ * consumers can rely on the indices for snapshot tests. `fact_history`
+ * (P0-2) and `fact_validate` (P1-4) are appended last so the original
+ * nine indices are unchanged. With `{ includeDeepRecall: true }` the
+ * gated `deep_recall` tool (P2-4) is appended as a twelfth, after the
+ * stable eleven.
+ *
+ * @stable
+ */
+declare function buildMemoryTools(deps: MemoryToolDeps, options?: BuildMemoryToolsOptions): ReadonlyArray<Tool>;
+//#endregion
+export { BuildMemoryToolsOptions, type MemoryToolDeps, type ScopeResolver, buildMemoryTools, createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool, createConversationSearchTool, createDeepRecallTool, createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool, createRecallEpisodesTool };
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/tools/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;UAyDiB,uBAAA;;;;;;;;;;;;;;;;;;iBAmBD,gBAAA,OACR,0BACG,0BACR,cAAc"}