@graphorin/memory 0.5.0

package/dist/tools/index.js

@@ -0,0 +1,36 @@
+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";
+
+//#region src/tools/index.ts
+/**
+* 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
+*/
+function buildMemoryTools(deps, options = {}) {
+	const tools = [
+		createBlockAppendTool(deps),
+		createBlockReplaceTool(deps),
+		createBlockRethinkTool(deps),
+		createFactRememberTool(deps),
+		createFactSearchTool(deps),
+		createFactSupersedeTool(deps),
+		createFactForgetTool(deps),
+		createRecallEpisodesTool(deps),
+		createConversationSearchTool(deps),
+		createFactHistoryTool(deps),
+		createFactValidateTool(deps)
+	];
+	if (options.includeDeepRecall === true) tools.push(createDeepRecallTool(deps));
+	return Object.freeze(tools);
+}
+
+//#endregion
+export { buildMemoryTools, createBlockAppendTool, createBlockReplaceTool, createBlockRethinkTool, createConversationSearchTool, createDeepRecallTool, createFactForgetTool, createFactHistoryTool, createFactRememberTool, createFactSearchTool, createFactSupersedeTool, createFactValidateTool, createRecallEpisodesTool };
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["tools: Tool[]"],"sources":["../../src/tools/index.ts"],"sourcesContent":["/**\n * Eleven memory tools registered with `@graphorin/tools` by the\n * `createMemory()` facade — plus an opt-in twelfth, `deep_recall` (P2-4),\n * appended only when iterative retrieval is configured. Each factory\n * takes a {@link MemoryToolDeps} bundle so consumers can scope the tool\n * surface (per-tier ACL, scope resolver, etc.) without rebuilding the\n * underlying memory facade.\n *\n * @packageDocumentation\n */\n\nimport type { Tool } from '@graphorin/core';\nimport {\n  createBlockAppendTool,\n  createBlockReplaceTool,\n  createBlockRethinkTool,\n} from './block-tools.js';\nimport {\n  createFactForgetTool,\n  createFactHistoryTool,\n  createFactRememberTool,\n  createFactSearchTool,\n  createFactSupersedeTool,\n  createFactValidateTool,\n} from './fact-tools.js';\nimport {\n  createConversationSearchTool,\n  createDeepRecallTool,\n  createRecallEpisodesTool,\n} from './recall-tools.js';\nimport type { MemoryToolDeps } from './types.js';\n\nexport {\n  createBlockAppendTool,\n  createBlockReplaceTool,\n  createBlockRethinkTool,\n} from './block-tools.js';\nexport {\n  createFactForgetTool,\n  createFactHistoryTool,\n  createFactRememberTool,\n  createFactSearchTool,\n  createFactSupersedeTool,\n  createFactValidateTool,\n} from './fact-tools.js';\nexport {\n  createConversationSearchTool,\n  createDeepRecallTool,\n  createRecallEpisodesTool,\n} from './recall-tools.js';\nexport type { MemoryToolDeps, ScopeResolver } from './types.js';\n\n/**\n * Options for {@link buildMemoryTools}.\n *\n * @stable\n */\nexport interface BuildMemoryToolsOptions {\n  /**\n   * Append the gated `deep_recall` tool (P2-4) as a twelfth tool. The\n   * facade sets this only when `iterativeRetrieval` is configured, so the\n   * default tool surface stays at the canonical eleven. Default `false`.\n   */\n  readonly includeDeepRecall?: boolean;\n}\n\n/**\n * Build the canonical eleven-memory-tool array. Order is stable —\n * consumers can rely on the indices for snapshot tests. `fact_history`\n * (P0-2) and `fact_validate` (P1-4) are appended last so the original\n * nine indices are unchanged. With `{ includeDeepRecall: true }` the\n * gated `deep_recall` tool (P2-4) is appended as a twelfth, after the\n * stable eleven.\n *\n * @stable\n */\nexport function buildMemoryTools(\n  deps: MemoryToolDeps,\n  options: BuildMemoryToolsOptions = {},\n): ReadonlyArray<Tool> {\n  const tools: Tool[] = [\n    createBlockAppendTool(deps) as Tool,\n    createBlockReplaceTool(deps) as Tool,\n    createBlockRethinkTool(deps) as Tool,\n    createFactRememberTool(deps) as Tool,\n    createFactSearchTool(deps) as Tool,\n    createFactSupersedeTool(deps) as Tool,\n    createFactForgetTool(deps) as Tool,\n    createRecallEpisodesTool(deps) as Tool,\n    createConversationSearchTool(deps) as Tool,\n    createFactHistoryTool(deps) as Tool,\n    createFactValidateTool(deps) as Tool,\n  ];\n  if (options.includeDeepRecall === true) {\n    tools.push(createDeepRecallTool(deps) as Tool);\n  }\n  return Object.freeze(tools);\n}\n"],"mappings":";;;;;;;;;;;;;;;AA4EA,SAAgB,iBACd,MACA,UAAmC,EAAE,EAChB;CACrB,MAAMA,QAAgB;EACpB,sBAAsB,KAAK;EAC3B,uBAAuB,KAAK;EAC5B,uBAAuB,KAAK;EAC5B,uBAAuB,KAAK;EAC5B,qBAAqB,KAAK;EAC1B,wBAAwB,KAAK;EAC7B,qBAAqB,KAAK;EAC1B,yBAAyB,KAAK;EAC9B,6BAA6B,KAAK;EAClC,sBAAsB,KAAK;EAC3B,uBAAuB,KAAK;EAC7B;AACD,KAAI,QAAQ,sBAAsB,KAChC,OAAM,KAAK,qBAAqB,KAAK,CAAS;AAEhD,QAAO,OAAO,OAAO,MAAM"}

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

@@ -0,0 +1,209 @@
+import { MemoryToolDeps } from "./types.js";
+import { Tool } from "@graphorin/core";
+import { z } from "zod";
+
+//#region src/tools/recall-tools.d.ts
+declare const recallEpisodesInputSchema: z.ZodObject<{
+  query: z.ZodString;
+  topK: z.ZodOptional<z.ZodNumber>;
+  dateRange: z.ZodOptional<z.ZodObject<{
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    from?: string | undefined;
+    to?: string | undefined;
+  }, {
+    from?: string | undefined;
+    to?: string | undefined;
+  }>>;
+}, "strip", z.ZodTypeAny, {
+  query: string;
+  topK?: number | undefined;
+  dateRange?: {
+    from?: string | undefined;
+    to?: string | undefined;
+  } | undefined;
+}, {
+  query: string;
+  topK?: number | undefined;
+  dateRange?: {
+    from?: string | undefined;
+    to?: string | undefined;
+  } | undefined;
+}>;
+declare const recallEpisodesOutputSchema: z.ZodObject<{
+  episodes: z.ZodArray<z.ZodObject<{
+    episodeId: z.ZodString;
+    summary: z.ZodString;
+    score: z.ZodNumber;
+    startedAt: z.ZodString;
+    endedAt: z.ZodString;
+    /** Trust-provenance tag (MST-10) — synthesized episodes say so. */
+    provenance: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    episodeId: string;
+    summary: string;
+    score: number;
+    startedAt: string;
+    endedAt: string;
+    provenance?: string | undefined;
+  }, {
+    episodeId: string;
+    summary: string;
+    score: number;
+    startedAt: string;
+    endedAt: string;
+    provenance?: string | undefined;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  episodes: {
+    episodeId: string;
+    summary: string;
+    score: number;
+    startedAt: string;
+    endedAt: string;
+    provenance?: string | undefined;
+  }[];
+}, {
+  episodes: {
+    episodeId: string;
+    summary: string;
+    score: number;
+    startedAt: string;
+    endedAt: string;
+    provenance?: string | undefined;
+  }[];
+}>;
+type RecallEpisodesInput = z.infer<typeof recallEpisodesInputSchema>;
+type RecallEpisodesOutput = z.infer<typeof recallEpisodesOutputSchema>;
+declare const conversationSearchInputSchema: z.ZodObject<{
+  query: z.ZodString;
+  topK: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+  query: string;
+  topK?: number | undefined;
+}, {
+  query: string;
+  topK?: number | undefined;
+}>;
+declare const conversationSearchOutputSchema: z.ZodObject<{
+  matches: z.ZodArray<z.ZodObject<{
+    messageId: z.ZodString;
+    score: z.ZodNumber;
+  }, "strip", z.ZodTypeAny, {
+    score: number;
+    messageId: string;
+  }, {
+    score: number;
+    messageId: string;
+  }>, "many">;
+}, "strip", z.ZodTypeAny, {
+  matches: {
+    score: number;
+    messageId: string;
+  }[];
+}, {
+  matches: {
+    score: number;
+    messageId: string;
+  }[];
+}>;
+type ConversationSearchInput = z.infer<typeof conversationSearchInputSchema>;
+type ConversationSearchOutput = z.infer<typeof conversationSearchOutputSchema>;
+declare const deepRecallInputSchema: z.ZodObject<{
+  query: z.ZodString;
+  topK: z.ZodOptional<z.ZodNumber>;
+  maxIterations: z.ZodOptional<z.ZodNumber>;
+  asOf: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+  query: string;
+  topK?: number | undefined;
+  maxIterations?: number | undefined;
+  asOf?: string | undefined;
+}, {
+  query: string;
+  topK?: number | undefined;
+  maxIterations?: number | undefined;
+  asOf?: string | undefined;
+}>;
+declare const deepRecallOutputSchema: z.ZodObject<{
+  hits: z.ZodArray<z.ZodObject<{
+    factId: z.ZodString;
+    text: z.ZodString;
+    score: z.ZodNumber;
+    sensitivity: z.ZodEnum<["public", "internal", "secret"]>;
+    /** Trust-provenance tag (MST-10) — synthesized facts say so. */
+    provenance: z.ZodOptional<z.ZodString>;
+  }, "strip", z.ZodTypeAny, {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: string | undefined;
+  }, {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: string | undefined;
+  }>, "many">;
+  sufficient: z.ZodBoolean;
+  abstained: z.ZodBoolean;
+  iterations: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+  hits: {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: string | undefined;
+  }[];
+  sufficient: boolean;
+  abstained: boolean;
+  iterations: number;
+}, {
+  hits: {
+    score: number;
+    factId: string;
+    text: string;
+    sensitivity: "public" | "internal" | "secret";
+    provenance?: string | undefined;
+  }[];
+  sufficient: boolean;
+  abstained: boolean;
+  iterations: number;
+}>;
+type DeepRecallInput = z.infer<typeof deepRecallInputSchema>;
+type DeepRecallOutput = z.infer<typeof deepRecallOutputSchema>;
+/**
+ * `recall_episodes` — triple-signal episode retrieval (recency ×
+ * relevance × importance).
+ *
+ * @stable
+ */
+declare function createRecallEpisodesTool(deps: MemoryToolDeps): Tool<RecallEpisodesInput, RecallEpisodesOutput>;
+/**
+ * `conversation_search` — FTS5 search over the active session
+ * messages.
+ *
+ * @stable
+ */
+declare function createConversationSearchTool(deps: MemoryToolDeps): Tool<ConversationSearchInput, ConversationSearchOutput>;
+/**
+ * `deep_recall` — gated, multi-pass ("deep") recall over the user's
+ * factual memory for HARD questions (P2-4). A local difficulty gate keeps
+ * simple lookups single-shot; only queries judged hard trigger a
+ * grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at
+ * 5), widening to one-hop graph expansion on reformulation passes. The
+ * output reports `abstained: true` when memory was insufficient even
+ * after reformulating — the agent should then say it lacks the
+ * information rather than guess. Registered only when the facade is
+ * created with `iterativeRetrieval`; otherwise it degrades to a single
+ * pass, so prefer the cheaper `fact_search` for ordinary lookups.
+ *
+ * @stable
+ */
+declare function createDeepRecallTool(deps: MemoryToolDeps): Tool<DeepRecallInput, DeepRecallOutput>;
+//#endregion
+export { createConversationSearchTool, createDeepRecallTool, createRecallEpisodesTool };
+//# sourceMappingURL=recall-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recall-tools.d.ts","names":[],"sources":["../../src/tools/recall-tools.ts"],"sourcesContent":[],"mappings":";;;;;cAKM,2BAAyB,CAAA,CAAA;;EAAzB,IAAA,eAAA,YASJ,CAAA;;;;;;;;;;;;EAT6B,KAAA,EAAA,MAAA;EAAA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAUzB,SAAA,CAAA,EAAA;;;;;;;;;;;;cAAA,0BAA0B,EAAA,CAAA,CAAA,SAAA,CAAA;EAAA,QAAA,YAAA,YAAA,CAAA;IAc3B,SAAA,aAAmB;IACnB,OAAA,aAAoB;IAEnB,KAAA,aAAA;;;;;EAA6B,CAAA,EAAA,OAAA,cAAA,EAAA;IAAA,SAAA,EAAA,MAAA;IAI7B,OAAA,EAAA,MAAA;;;;;;;IAA8B,OAAA,EAAA,MAAA;IAAA,KAAA,EAAA,MAAA;IAS/B,SAAA,EAAA,MAAA;IACA,OAAA,EAAA,MAAA;IAGC,UAAA,CAAA,EAAA,MAAA,GAKJ,SAAA;;;;;;;;;IALyB,UAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAA,CAAA,EAAA;AAAA,CAAA,EAAA;;;;;;;;;;KApBtB,mBAAA,GAAsB,CAAA,CAAE,aAAa;KACrC,oBAAA,GAAuB,CAAA,CAAE,aAAa;cAErC,+BAA6B,CAAA,CAAA;;EAuBP,IAAA,eAAA,YAAA,CAAA;CAAA,EAAA,OAAA,cAAA,EAAA;EAgBvB,KAAA,EAAA,MAAA;EACA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAgB;AAQrB,CAAA,EAAA;EACQ,KAAA,EAAA,MAAA;EACA,IAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CAAqB,CAAA;cA9CvB,8BA8CH,EA9CiC,CAAA,CAAA,SA8CjC,CAAA;EAAI,OAAA,YAAA,YAAA,CAAA;IAiDS,SAAA,aAAA;IACR,KAAA,aAAA;EACA,CAAA,EAAA,OAAA,cAAA,EAAA;IAAyB,KAAA,EAAA,MAAA;IAA9B,SAAA,EAAA,MAAA;EAAI,CAAA,EAAA;IA0CS,KAAA,EAAA,MAAA;IACR,SAAA,EAAA,MAAA;EACA,CAAA,CAAA,EAAA,MAAA,CAAA;CAAiB,EAAA,OAAA,cAAA,EAAA;EAAtB,OAAA,EAAA;IAAI,KAAA,EAAA,MAAA;;;;;;;;;KApIF,uBAAA,GAA0B,CAAA,CAAE,aAAa;KACzC,wBAAA,GAA2B,CAAA,CAAE,aAAa;cAGzC,uBAAqB,CAAA,CAAA;;;;;;;;;;;;;;;;cAMrB,wBAAsB,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAgBvB,eAAA,GAAkB,CAAA,CAAE,aAAa;KACjC,gBAAA,GAAmB,CAAA,CAAE,aAAa;;;;;;;iBAQvB,wBAAA,OACR,iBACL,KAAK,qBAAqB;;;;;;;iBAiDb,4BAAA,OACR,iBACL,KAAK,yBAAyB;;;;;;;;;;;;;;;iBA0CjB,oBAAA,OACR,iBACL,KAAK,iBAAiB"}

package/dist/tools/recall-tools.js

@@ -0,0 +1,170 @@
+import { tool } from "@graphorin/tools";
+import { z } from "zod";
+
+//#region src/tools/recall-tools.ts
+const recallEpisodesInputSchema = z.object({
+	query: z.string().min(1).max(1024),
+	topK: z.number().int().positive().max(20).optional(),
+	dateRange: z.object({
+		from: z.string().datetime().optional(),
+		to: z.string().datetime().optional()
+	}).optional()
+});
+const recallEpisodesOutputSchema = z.object({ episodes: z.array(z.object({
+	episodeId: z.string(),
+	summary: z.string(),
+	score: z.number(),
+	startedAt: z.string(),
+	endedAt: z.string(),
+	provenance: z.string().optional()
+})) });
+const conversationSearchInputSchema = z.object({
+	query: z.string().min(1).max(1024),
+	topK: z.number().int().positive().max(20).optional()
+});
+const conversationSearchOutputSchema = z.object({ matches: z.array(z.object({
+	messageId: z.string(),
+	score: z.number()
+})) });
+const deepRecallSensitivityEnum = z.enum([
+	"public",
+	"internal",
+	"secret"
+]);
+const deepRecallInputSchema = z.object({
+	query: z.string().min(1).max(1024),
+	topK: z.number().int().positive().max(50).optional(),
+	maxIterations: z.number().int().min(1).max(5).optional(),
+	asOf: z.string().datetime().optional()
+});
+const deepRecallOutputSchema = z.object({
+	hits: z.array(z.object({
+		factId: z.string(),
+		text: z.string(),
+		score: z.number(),
+		sensitivity: deepRecallSensitivityEnum,
+		provenance: z.string().optional()
+	})),
+	sufficient: z.boolean(),
+	abstained: z.boolean(),
+	iterations: z.number().int()
+});
+/**
+* `recall_episodes` — triple-signal episode retrieval (recency ×
+* relevance × importance).
+*
+* @stable
+*/
+function createRecallEpisodesTool(deps) {
+	return tool({
+		name: "recall_episodes",
+		description: "Recall summarized episodes (multi-message stretches of past activity) matching a natural-language query. Combines vector relevance, time-decay recency, and the per-episode importance score. Use for long-horizon recall ('the last time we discussed X').",
+		inputSchema: recallEpisodesInputSchema,
+		outputSchema: recallEpisodesOutputSchema,
+		sideEffectClass: "read-only",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "pure",
+		tags: ["memory", "episodic"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const dateRange = input.dateRange !== void 0 ? {
+				...input.dateRange.from !== void 0 ? { from: input.dateRange.from } : {},
+				...input.dateRange.to !== void 0 ? { to: input.dateRange.to } : {}
+			} : void 0;
+			return { episodes: (await deps.episodic.search(scope, input.query, {
+				...input.topK !== void 0 ? { topK: input.topK } : {},
+				...dateRange !== void 0 ? { dateRange } : {},
+				signal: ctx.signal
+			})).map((hit) => ({
+				episodeId: hit.record.id,
+				summary: hit.record.summary,
+				score: hit.score,
+				startedAt: hit.record.startedAt,
+				endedAt: hit.record.endedAt,
+				...hit.record.provenance !== void 0 ? { provenance: hit.record.provenance } : {}
+			})) };
+		}
+	});
+}
+/**
+* `conversation_search` — FTS5 search over the active session
+* messages.
+*
+* @stable
+*/
+function createConversationSearchTool(deps) {
+	return tool({
+		name: "conversation_search",
+		description: "Search the active session message log by natural-language query. Returns up to `topK` matched messages with their stable id and BM25 score.",
+		inputSchema: conversationSearchInputSchema,
+		outputSchema: conversationSearchOutputSchema,
+		sideEffectClass: "read-only",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "pure",
+		tags: ["memory", "session"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			return { matches: (await deps.session.search(scope, input.query, {
+				...input.topK !== void 0 ? { topK: input.topK } : {},
+				signal: ctx.signal
+			})).map((hit) => ({
+				messageId: hit.record.id,
+				score: hit.score
+			})) };
+		}
+	});
+}
+/**
+* `deep_recall` — gated, multi-pass ("deep") recall over the user's
+* factual memory for HARD questions (P2-4). A local difficulty gate keeps
+* simple lookups single-shot; only queries judged hard trigger a
+* grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at
+* 5), widening to one-hop graph expansion on reformulation passes. The
+* output reports `abstained: true` when memory was insufficient even
+* after reformulating — the agent should then say it lacks the
+* information rather than guess. Registered only when the facade is
+* created with `iterativeRetrieval`; otherwise it degrades to a single
+* pass, so prefer the cheaper `fact_search` for ordinary lookups.
+*
+* @stable
+*/
+function createDeepRecallTool(deps) {
+	return tool({
+		name: "deep_recall",
+		description: "Multi-pass ('deep') recall over the user's long-term factual memory for HARD multi-hop or temporal questions one search can't answer (e.g. 'who recommended the book the person I met in Tbilisi mentioned?'). A difficulty gate keeps simple lookups single-shot; hard questions trigger a bounded grade-and-reformulate loop. If `abstained` is true the memory was insufficient even after reformulating — tell the user you don't have enough stored to answer and DO NOT guess. Prefer the cheaper fact_search for ordinary lookups.",
+		inputSchema: deepRecallInputSchema,
+		outputSchema: deepRecallOutputSchema,
+		sideEffectClass: "read-only",
+		sandboxPolicy: "none",
+		sensitivity: "internal",
+		memoryGuardTier: "pure",
+		tags: ["memory", "semantic"],
+		async execute(input, ctx) {
+			const scope = await deps.resolveScope(ctx);
+			const result = await deps.semantic.searchIterative(scope, input.query, {
+				...input.topK !== void 0 ? { topK: input.topK } : {},
+				...input.maxIterations !== void 0 ? { maxIterations: input.maxIterations } : {},
+				...input.asOf !== void 0 ? { asOf: input.asOf } : {},
+				signal: ctx.signal
+			});
+			return {
+				hits: result.hits.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 } : {}
+				})),
+				sufficient: result.sufficient,
+				abstained: result.abstained,
+				iterations: result.iterations
+			};
+		}
+	});
+}
+
+//#endregion
+export { createConversationSearchTool, createDeepRecallTool, createRecallEpisodesTool };
+//# sourceMappingURL=recall-tools.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recall-tools.js","names":[],"sources":["../../src/tools/recall-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 recallEpisodesInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(20).optional(),\n  dateRange: z\n    .object({\n      from: z.string().datetime().optional(),\n      to: z.string().datetime().optional(),\n    })\n    .optional(),\n});\nconst recallEpisodesOutputSchema = z.object({\n  episodes: z.array(\n    z.object({\n      episodeId: z.string(),\n      summary: z.string(),\n      score: z.number(),\n      startedAt: z.string(),\n      endedAt: z.string(),\n      /** Trust-provenance tag (MST-10) — synthesized episodes say so. */\n      provenance: z.string().optional(),\n    }),\n  ),\n});\n\ntype RecallEpisodesInput = z.infer<typeof recallEpisodesInputSchema>;\ntype RecallEpisodesOutput = z.infer<typeof recallEpisodesOutputSchema>;\n\nconst conversationSearchInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(20).optional(),\n});\nconst conversationSearchOutputSchema = z.object({\n  matches: z.array(\n    z.object({\n      messageId: z.string(),\n      score: z.number(),\n    }),\n  ),\n});\n\ntype ConversationSearchInput = z.infer<typeof conversationSearchInputSchema>;\ntype ConversationSearchOutput = z.infer<typeof conversationSearchOutputSchema>;\n\nconst deepRecallSensitivityEnum = z.enum(['public', 'internal', 'secret']);\nconst deepRecallInputSchema = z.object({\n  query: z.string().min(1).max(1024),\n  topK: z.number().int().positive().max(50).optional(),\n  maxIterations: z.number().int().min(1).max(5).optional(),\n  asOf: z.string().datetime().optional(),\n});\nconst deepRecallOutputSchema = z.object({\n  hits: z.array(\n    z.object({\n      factId: z.string(),\n      text: z.string(),\n      score: z.number(),\n      sensitivity: deepRecallSensitivityEnum,\n      /** Trust-provenance tag (MST-10) — synthesized facts say so. */\n      provenance: z.string().optional(),\n    }),\n  ),\n  sufficient: z.boolean(),\n  abstained: z.boolean(),\n  iterations: z.number().int(),\n});\n\ntype DeepRecallInput = z.infer<typeof deepRecallInputSchema>;\ntype DeepRecallOutput = z.infer<typeof deepRecallOutputSchema>;\n\n/**\n * `recall_episodes` — triple-signal episode retrieval (recency ×\n * relevance × importance).\n *\n * @stable\n */\nexport function createRecallEpisodesTool(\n  deps: MemoryToolDeps,\n): Tool<RecallEpisodesInput, RecallEpisodesOutput> {\n  return tool<RecallEpisodesInput, RecallEpisodesOutput>({\n    name: 'recall_episodes',\n    description:\n      \"Recall summarized episodes (multi-message stretches of past activity) matching a natural-language query. Combines vector relevance, time-decay recency, and the per-episode importance score. Use for long-horizon recall ('the last time we discussed X').\",\n    inputSchema: recallEpisodesInputSchema,\n    outputSchema: recallEpisodesOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'episodic'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const dateRange =\n        input.dateRange !== undefined\n          ? {\n              ...(input.dateRange.from !== undefined ? { from: input.dateRange.from } : {}),\n              ...(input.dateRange.to !== undefined ? { to: input.dateRange.to } : {}),\n            }\n          : undefined;\n      const hits = await deps.episodic.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        ...(dateRange !== undefined ? { dateRange } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        episodes: hits.map((hit) => ({\n          episodeId: hit.record.id,\n          summary: hit.record.summary,\n          score: hit.score,\n          startedAt: hit.record.startedAt,\n          endedAt: hit.record.endedAt,\n          // MST-10: surface origin so a consumer can tell a synthesized\n          // (consolidator-extracted) episode from a first-party record —\n          // recalled text re-enters the model as trusted tool output.\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `conversation_search` — FTS5 search over the active session\n * messages.\n *\n * @stable\n */\nexport function createConversationSearchTool(\n  deps: MemoryToolDeps,\n): Tool<ConversationSearchInput, ConversationSearchOutput> {\n  return tool<ConversationSearchInput, ConversationSearchOutput>({\n    name: 'conversation_search',\n    description:\n      'Search the active session message log by natural-language query. Returns up to `topK` matched messages with their stable id and BM25 score.',\n    inputSchema: conversationSearchInputSchema,\n    outputSchema: conversationSearchOutputSchema,\n    sideEffectClass: 'read-only',\n    sandboxPolicy: 'none',\n    sensitivity: 'internal',\n    memoryGuardTier: 'pure',\n    tags: ['memory', 'session'],\n    async execute(input, ctx) {\n      const scope = await deps.resolveScope(ctx);\n      const hits = await deps.session.search(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        matches: hits.map((hit) => ({\n          messageId: hit.record.id,\n          score: hit.score,\n        })),\n      };\n    },\n  });\n}\n\n/**\n * `deep_recall` — gated, multi-pass (\"deep\") recall over the user's\n * factual memory for HARD questions (P2-4). A local difficulty gate keeps\n * simple lookups single-shot; only queries judged hard trigger a\n * grade-and-reformulate loop (bounded by `maxIterations`, hard-capped at\n * 5), widening to one-hop graph expansion on reformulation passes. The\n * output reports `abstained: true` when memory was insufficient even\n * after reformulating — the agent should then say it lacks the\n * information rather than guess. Registered only when the facade is\n * created with `iterativeRetrieval`; otherwise it degrades to a single\n * pass, so prefer the cheaper `fact_search` for ordinary lookups.\n *\n * @stable\n */\nexport function createDeepRecallTool(\n  deps: MemoryToolDeps,\n): Tool<DeepRecallInput, DeepRecallOutput> {\n  return tool<DeepRecallInput, DeepRecallOutput>({\n    name: 'deep_recall',\n    description:\n      \"Multi-pass ('deep') recall over the user's long-term factual memory for HARD multi-hop or temporal questions one search can't answer (e.g. 'who recommended the book the person I met in Tbilisi mentioned?'). A difficulty gate keeps simple lookups single-shot; hard questions trigger a bounded grade-and-reformulate loop. If `abstained` is true the memory was insufficient even after reformulating — tell the user you don't have enough stored to answer and DO NOT guess. Prefer the cheaper fact_search for ordinary lookups.\",\n    inputSchema: deepRecallInputSchema,\n    outputSchema: deepRecallOutputSchema,\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 result = await deps.semantic.searchIterative(scope, input.query, {\n        ...(input.topK !== undefined ? { topK: input.topK } : {}),\n        ...(input.maxIterations !== undefined ? { maxIterations: input.maxIterations } : {}),\n        ...(input.asOf !== undefined ? { asOf: input.asOf } : {}),\n        signal: ctx.signal,\n      });\n      return {\n        hits: result.hits.map((hit) => ({\n          factId: hit.record.id,\n          text: hit.record.text,\n          score: hit.score,\n          sensitivity: hit.record.sensitivity,\n          // MST-10: origin annotation, mirroring fact_search.\n          ...(hit.record.provenance !== undefined ? { provenance: hit.record.provenance } : {}),\n        })),\n        sufficient: result.sufficient,\n        abstained: result.abstained,\n        iterations: result.iterations,\n      };\n    },\n  });\n}\n"],"mappings":"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"}

package/dist/tools/types.d.ts

@@ -0,0 +1,40 @@
+import { EpisodicMemory } from "../tiers/episodic-memory.js";
+import { SemanticMemory } from "../tiers/semantic-memory.js";
+import { ProceduralMemory } from "../tiers/procedural-memory.js";
+import { SessionMemory } from "../tiers/session-memory.js";
+import { SharedMemory } from "../tiers/shared-memory.js";
+import { WorkingMemory } from "../tiers/working-memory.js";
+import * as _graphorin_core0 from "@graphorin/core";
+import { SessionScope } from "@graphorin/core";
+
+//#region src/tools/types.d.ts
+
+/**
+ * Resolver that produces the live {@link SessionScope} for the tool
+ * call from the surrounding agent run context. The agent runtime
+ * (Phase 12) supplies a closure that reads `RunContext` directly;
+ * standalone callers can pass a fixed scope.
+ *
+ * @stable
+ */
+type ScopeResolver = (ctx: _graphorin_core0.ToolExecutionContext<unknown>) => SessionScope | Promise<SessionScope>;
+/**
+ * Dependency bundle threaded into every memory tool. Exposed
+ * separately from the {@link Tool} surface so the executor can scope
+ * the dependencies per call without leaking the wider memory facade
+ * into the tool author surface.
+ *
+ * @stable
+ */
+interface MemoryToolDeps {
+  readonly working: WorkingMemory;
+  readonly session: SessionMemory;
+  readonly episodic: EpisodicMemory;
+  readonly semantic: SemanticMemory;
+  readonly procedural: ProceduralMemory;
+  readonly shared: SharedMemory;
+  readonly resolveScope: ScopeResolver;
+}
+//#endregion
+export { MemoryToolDeps, ScopeResolver };
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/tools/types.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;AAgBA;;;;;AAE2B,KAFf,aAAA,GAEe,CAAA,GAAA,EAFF,gBAAA,CACQ,oBACN,CAAA,OAAA,CAAA,EAAA,GAAtB,YAAsB,GAAP,OAAO,CAAC,YAAD,CAAA;AAU3B;;;;;;;;AAOsC,UAPrB,cAAA,CAOqB;oBANlB;oBACA;qBACC;qBACA;uBACE;mBACJ;yBACM"}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@graphorin/memory",
+  "version": "0.5.0",
+  "description": "Six-tier memory system for the Graphorin framework: createMemory() facade with working / session / episodic / semantic / procedural / shared sub-modules, eleven memory tools wired into @graphorin/tools, hybrid vector + FTS5 search composed through Reciprocal Rank Fusion (k=60 default) with a pluggable reranker hook, a multi-stage conflict resolution pipeline (exact dedup → embedding three-zone → heuristic regex → subject/predicate → defer-to-deep) with an English locale pack default + plug-in locales, an embedder migration runner with three coexistence policies (lock-on-first / multi-active / auto-migrate), per-record embedder_id enforcement, multi-agent attribution, append-only writes with soft-delete + supersede semantics, default-on bi-temporal storage, provenance + quarantine safety gate for synthesized memory, AISpan emission for every operation, and tier-aware memory-modification guard wiring.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/memory",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/memory"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "memory",
+    "long-term-memory",
+    "working-memory",
+    "session-memory",
+    "episodic-memory",
+    "semantic-memory",
+    "procedural-memory",
+    "shared-memory",
+    "rrf",
+    "hybrid-search",
+    "rerank",
+    "conflict-resolution",
+    "embedder-migration",
+    "bi-temporal",
+    "multi-agent"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./facade": {
+      "types": "./dist/facade.d.ts",
+      "import": "./dist/facade.js"
+    },
+    "./tiers": {
+      "types": "./dist/tiers/index.d.ts",
+      "import": "./dist/tiers/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
+    },
+    "./search": {
+      "types": "./dist/search/index.d.ts",
+      "import": "./dist/search/index.js"
+    },
+    "./conflict": {
+      "types": "./dist/conflict/index.d.ts",
+      "import": "./dist/conflict/index.js"
+    },
+    "./migration": {
+      "types": "./dist/migration/index.d.ts",
+      "import": "./dist/migration/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0",
+    "@graphorin/observability": "0.5.0",
+    "@graphorin/security": "0.5.0",
+    "@graphorin/tools": "0.5.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.9.0",
+    "fast-check": "^3.23.0",
+    "zod": "^3.25.0",
+    "@graphorin/store-sqlite": "0.5.0",
+    "@graphorin/embedder-transformersjs": "0.5.0",
+    "@graphorin/triggers": "0.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}