Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

feat(memory): wire governed memory tools into Mastra (#52)

Leoe4ff78919c7e
diff --git a/apps/server/integration/OrchestrationEngineHarness.integration.ts b/apps/server/integration/OrchestrationEngineHarness.integration.ts
index 6bff12bef..3d829c5e1 100644
--- a/apps/server/integration/OrchestrationEngineHarness.integration.ts
+++ b/apps/server/integration/OrchestrationEngineHarness.integration.ts
@@ -40,6 +40,9 @@ import { makeProviderRegistryLayer } from "../src/provider/testUtils/providerReg
import { ProviderSessionDirectoryLive } from "../src/provider/Layers/ProviderSessionDirectory.ts";
import { ServerSettingsService } from "../src/serverSettings.ts";
import { AgentControllerLive } from "../src/provider/Layers/AgentController.ts";
+import { EntityMemoryRepositoryLive } from "../src/memory/Layers/EntityMemoryRepository.ts";
+import { MemoryCandidateRepositoryLive } from "../src/memory/Layers/MemoryCandidateRepository.ts";
+import { MemoryRevisionWriteLockLive } from "../src/memory/Services/MemoryRevisionWriteLock.ts";
import { LegacyProviderBridgeLive } from "../src/provider/Layers/LegacyProviderBridge.ts";
import { makeProviderServiceLive } from "../src/provider/Layers/ProviderService.ts";
import { makeCodexAdapter } from "../src/provider/Layers/CodexAdapter.ts";
@@ -266,6 +269,10 @@ export const makeOrchestrationIntegrationHarness = (
yield* initializeGitWorkspace(workspaceDir);
const persistenceLayer = makeSqlitePersistenceLive(dbPath);
+ const memoryRepositoriesLayer = Layer.mergeAll(
+ EntityMemoryRepositoryLive,
+ MemoryCandidateRepositoryLive,
+ ).pipe(Layer.provide(MemoryRevisionWriteLockLive), Layer.provide(persistenceLayer));
const orchestrationLayer = OrchestrationEngineLive.pipe(
Layer.provide(OrchestrationProjectionPipelineLive),
Layer.provide(OrchestrationEventStoreLive),
@@ -303,7 +310,10 @@ export const makeOrchestrationIntegrationHarness = (
Layer.provide(providerEventLoggersLayer),
);
const legacyProviderLayer = LegacyProviderBridgeLive.pipe(Layer.provide(providerLayer));
- const agentControllerLayer = AgentControllerLive.pipe(Layer.provide(legacyProviderLayer));
+ const agentControllerLayer = AgentControllerLive.pipe(
+ Layer.provide(memoryRepositoriesLayer),
+ Layer.provide(legacyProviderLayer),
+ );
const providerRegistryLayer = makeProviderRegistryLayer();
const checkpointStoreLayer = CheckpointStore.layer.pipe(Layer.provide(VcsDriverRegistry.layer));
diff --git a/apps/server/src/memory/MemoryToolHandlers.ts b/apps/server/src/memory/MemoryToolHandlers.ts
index 3ae5ed807..6934599e8 100644
--- a/apps/server/src/memory/MemoryToolHandlers.ts
+++ b/apps/server/src/memory/MemoryToolHandlers.ts
@@ -6,6 +6,8 @@ import {
AkeruMemoryEntityId,
AkeruMemoryId,
AkeruMemoryRootId,
+ PositiveInt,
+ TrimmedNonEmptyString,
type AkeruMemoryCandidateDecision,
type AkeruMemoryDecisionReceipt,
type AkeruMemoryRevision,
@@ -15,6 +17,7 @@ import {
} from "@t3tools/contracts";
import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
import type { AkeruToolExecution } from "../provider/AkeruToolRuntime.ts";
import { deriveAkeruWorkspaceId, resolveAuthorizedMemoryPartitions } from "./EntityMemoryAccess.ts";
@@ -23,6 +26,32 @@ import type { MemoryCandidateRepositoryShape } from "./Services/MemoryCandidateR
export type AkeruMemoryToolId = "recall_memory" | "remember" | "update_memory" | "forget_memory";
+const MemoryTargetScope = Schema.Literals(["private", "bot", "project", "group", "workspace"]);
+
+export const AkeruMemoryToolInputSchemas = {
+ recall_memory: Schema.Struct({
+ query: TrimmedNonEmptyString,
+ limit: Schema.optional(PositiveInt),
+ includeSensitive: Schema.optional(Schema.Boolean),
+ }),
+ remember: Schema.Struct({
+ fact: TrimmedNonEmptyString,
+ scope: MemoryTargetScope,
+ sensitive: Schema.optional(Schema.Boolean),
+ }),
+ update_memory: Schema.Struct({
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ fact: TrimmedNonEmptyString,
+ scope: MemoryTargetScope,
+ sensitive: Schema.optional(Schema.Boolean),
+ }),
+ forget_memory: Schema.Struct({
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ }),
+} as const;
+
export type AkeruMemoryToolHandler = (
input: Omit<AkeruToolExecution, "toolId"> & { readonly toolId: AkeruMemoryToolId },
) => Promise<unknown>;
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index be63254b6..d2ed24299 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -649,6 +649,17 @@ describe("ProviderCommandReactor", () => {
model: "gpt-5-codex",
},
mcpServers: [],
+ memoryAccess: {
+ tenantId: "local",
+ userId: "owner",
+ threadId: "thread-1",
+ projectId: "project-1",
+ workspaceRoot: "/tmp/provider-project",
+ botId: null,
+ groupId: null,
+ respondingBotId: null,
+ groupMemberBotIds: [],
+ },
botSandbox: null,
runtimeMode: "approval-required",
});
@@ -2437,6 +2448,7 @@ describe("ProviderCommandReactor", () => {
expect(harness.startSession.mock.calls[1]?.[1]).toMatchObject({
threadId: ThreadId.make("thread-1"),
cwd: "/tmp/provider-project-worktree",
+ memoryAccess: { workspaceRoot: "/tmp/provider-project" },
resumeCursor: { opaque: "resume-1" },
modelSelection: {
instanceId: ProviderInstanceId.make("claudeAgent"),
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index 4b5f047aa..519214d84 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -1,4 +1,6 @@
import {
+ AkeruMemoryTenantId,
+ AkeruMemoryUserId,
AkeruUsageReservationId,
type ChatAttachment,
CommandId,
@@ -696,6 +698,12 @@ const make = Effect.gen(function* () {
: yield* projectionBotRepository
.getById({ botId: respondingBotId })
.pipe(Effect.map(Option.getOrUndefined));
+ const respondingGroup =
+ thread.groupId == null
+ ? undefined
+ : (yield* projectionSnapshotQuery.getCommandReadModel()).groups.find(
+ (group) => group.id === thread.groupId,
+ );
const effectiveCwd = resolveThreadWorkspaceCwd({
thread,
projects: project ? [project] : [],
@@ -723,6 +731,21 @@ const make = Effect.gen(function* () {
mcpServers,
...(respondingBotId ? { botId: respondingBotId } : {}),
...(respondingBot ? { botName: respondingBot.name } : {}),
+ ...(project
+ ? {
+ memoryAccess: {
+ tenantId: AkeruMemoryTenantId.make("local"),
+ userId: AkeruMemoryUserId.make("owner"),
+ threadId,
+ projectId: thread.projectId,
+ workspaceRoot: project.workspaceRoot,
+ botId: thread.groupId == null ? respondingBotId : null,
+ groupId: thread.groupId ?? null,
+ respondingBotId,
+ groupMemberBotIds: respondingGroup?.members.map((member) => member.botId) ?? [],
+ },
+ }
+ : {}),
botSandbox: respondingBot?.sandbox ?? null,
botSandboxBrowserSharing,
...(input?.resumeCursor !== undefined ? { resumeCursor: input.resumeCursor } : {}),
diff --git a/apps/server/src/provider/AkeruMastraTools.test.ts b/apps/server/src/provider/AkeruMastraTools.test.ts
index 940117e3d..0436e8e21 100644
--- a/apps/server/src/provider/AkeruMastraTools.test.ts
+++ b/apps/server/src/provider/AkeruMastraTools.test.ts
@@ -1,7 +1,7 @@
import { AKERU_TOOL_CATALOG } from "@t3tools/contracts";
import { describe, expect, it, vi } from "vite-plus/test";
-import type { AkeruToolRuntime } from "./AkeruToolRuntime.ts";
+import { createAkeruToolRuntime, type AkeruToolRuntime } from "./AkeruToolRuntime.ts";
import { createAkeruMastraTools } from "./AkeruMastraTools.ts";
describe("createAkeruMastraTools", () => {
@@ -31,4 +31,31 @@ describe("createAkeruMastraTools", () => {
"has no call identity",
);
});
+
+ it("builds registered memory handlers as Mastra tools", async () => {
+ const rememberHandler = vi.fn(async () => ({ saved: true }));
+ const unavailable = vi.fn(async () => undefined);
+ const runtime = createAkeruToolRuntime();
+ runtime.registerSession("thread-memory", {
+ runtimeMode: "full-access",
+ workspaceType: "none",
+ memoryHandlers: {
+ recall_memory: unavailable,
+ remember: rememberHandler,
+ update_memory: unavailable,
+ forget_memory: unavailable,
+ },
+ });
+ const remember = createAkeruMastraTools("thread-memory", runtime).remember as {
+ readonly execute?: (input: unknown, context: unknown) => Promise<unknown>;
+ };
+ if (!remember?.execute) throw new Error("Remember tool is unavailable.");
+
+ await expect(
+ remember.execute({ fact: "The user prefers vim.", scope: "private" }, {
+ agent: { toolCallId: "memory-1" },
+ } as never),
+ ).resolves.toEqual({ saved: true });
+ expect(rememberHandler).toHaveBeenCalledOnce();
+ });
});
diff --git a/apps/server/src/provider/AkeruMastraTools.ts b/apps/server/src/provider/AkeruMastraTools.ts
index 907ba4994..14f2cc22e 100644
--- a/apps/server/src/provider/AkeruMastraTools.ts
+++ b/apps/server/src/provider/AkeruMastraTools.ts
@@ -4,12 +4,23 @@ import { AkeruToolInputSchemas } from "@t3tools/contracts";
import * as Schema from "effect/Schema";
import { z } from "zod";
-import type { AkeruToolRuntime } from "./AkeruToolRuntime.ts";
+import {
+ isMemoryToolId,
+ type AkeruRuntimeToolId,
+ type AkeruToolRuntime,
+} from "./AkeruToolRuntime.ts";
+import { AkeruMemoryToolInputSchemas } from "../memory/MemoryToolHandlers.ts";
+
+function inputSchema(toolId: AkeruRuntimeToolId) {
+ return isMemoryToolId(toolId)
+ ? AkeruMemoryToolInputSchemas[toolId]
+ : AkeruToolInputSchemas[toolId];
+}
export function createAkeruMastraTools(threadId: string, runtime: AkeruToolRuntime): ToolsInput {
return Object.fromEntries(
runtime.toolsForThread(threadId).map((definition) => {
- const schema = AkeruToolInputSchemas[definition.id];
+ const schema = inputSchema(definition.id);
const standardSchema = Schema.toStandardJSONSchemaV1(schema);
const approval = (input: unknown) => runtime.requiresApproval(threadId, definition.id, input);
const tool = createTool({
diff --git a/apps/server/src/provider/AkeruToolRuntime.test.ts b/apps/server/src/provider/AkeruToolRuntime.test.ts
index e7dd5b3a7..2adbe69c5 100644
--- a/apps/server/src/provider/AkeruToolRuntime.test.ts
+++ b/apps/server/src/provider/AkeruToolRuntime.test.ts
@@ -4,7 +4,7 @@ import * as NodeOS from "node:os";
import * as NodePath from "node:path";
import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";
-import { afterEach, describe, expect, it } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
import { BotId } from "@t3tools/contracts";
import { createAkeruToolRuntime } from "./AkeruToolRuntime.ts";
@@ -42,6 +42,47 @@ describe("AkeruToolRuntime", () => {
]);
});
+ it("exposes registered memory handlers and protects sensitive writes", async () => {
+ const remember = vi.fn(async () => ({ saved: true }));
+ const unavailable = vi.fn(async () => undefined);
+ const runtime = createAkeruToolRuntime();
+ runtime.registerSession("thread-memory", {
+ runtimeMode: "full-access",
+ workspaceType: "none",
+ memoryHandlers: {
+ recall_memory: unavailable,
+ remember,
+ update_memory: unavailable,
+ forget_memory: unavailable,
+ },
+ });
+
+ expect(runtime.toolsForThread("thread-memory").map((tool) => tool.id)).toEqual([
+ "recall_memory",
+ "remember",
+ "update_memory",
+ "forget_memory",
+ ]);
+ const privateWrite = {
+ threadId: "thread-memory",
+ toolId: "remember" as const,
+ toolCallId: "private-write",
+ input: { fact: "The user prefers vim.", scope: "private" },
+ approvalMode: "require-grant" as const,
+ };
+ await expect(runtime.execute(privateWrite)).resolves.toEqual({ saved: true });
+
+ const sensitiveWrite = {
+ ...privateWrite,
+ toolCallId: "sensitive-write",
+ input: { fact: " The user prefers vim. ", scope: "private", sensitive: true },
+ };
+ await expect(runtime.execute(sensitiveWrite)).rejects.toThrow("requires approval");
+ runtime.grantApproval(sensitiveWrite);
+ await expect(runtime.execute(sensitiveWrite)).resolves.toEqual({ saved: true });
+ expect(remember).toHaveBeenCalledTimes(2);
+ });
+
it("requires an exact one-shot grant for local shell commands", async () => {
const runtime = createAkeruToolRuntime();
runtime.registerSession("thread-1", {
diff --git a/apps/server/src/provider/AkeruToolRuntime.ts b/apps/server/src/provider/AkeruToolRuntime.ts
index 01f8f587f..e139e2c2b 100644
--- a/apps/server/src/provider/AkeruToolRuntime.ts
+++ b/apps/server/src/provider/AkeruToolRuntime.ts
@@ -14,6 +14,36 @@ import {
import * as Schema from "effect/Schema";
import type { UserActionIncidentInput } from "../bot-inbox/userActionIncidents.ts";
+import {
+ AkeruMemoryToolInputSchemas,
+ type AkeruMemoryToolHandler,
+ type AkeruMemoryToolId,
+} from "../memory/MemoryToolHandlers.ts";
+
+export type AkeruRuntimeToolId = AkeruToolId | AkeruMemoryToolId;
+
+export interface AkeruRuntimeToolDefinition {
+ readonly id: AkeruRuntimeToolId;
+ readonly description: string;
+}
+
+const MEMORY_TOOL_DEFINITIONS = [
+ { id: "recall_memory", description: "Search approved memory for the current turn." },
+ { id: "remember", description: "Propose a durable fact for the current user and bot context." },
+ { id: "update_memory", description: "Propose a revision to an authorized durable fact." },
+ { id: "forget_memory", description: "Forget an authorized durable fact immediately." },
+] as const satisfies ReadonlyArray<AkeruRuntimeToolDefinition>;
+
+const MEMORY_TOOL_INPUT_DECODERS = {
+ recall_memory: Schema.decodeUnknownSync(AkeruMemoryToolInputSchemas.recall_memory),
+ remember: Schema.decodeUnknownSync(AkeruMemoryToolInputSchemas.remember),
+ update_memory: Schema.decodeUnknownSync(AkeruMemoryToolInputSchemas.update_memory),
+ forget_memory: Schema.decodeUnknownSync(AkeruMemoryToolInputSchemas.forget_memory),
+} as const;
+
+export function isMemoryToolId(toolId: string): toolId is AkeruMemoryToolId {
+ return Object.hasOwn(AkeruMemoryToolInputSchemas, toolId);
+}
export interface AkeruToolSession {
readonly botId?: BotId;
@@ -22,6 +52,7 @@ export interface AkeruToolSession {
readonly workspaceType: AkeruToolWorkspaceType;
readonly workspace?: Workspace;
readonly userComputerWorkspace?: Workspace;
+ readonly memoryHandlers?: Record<AkeruMemoryToolId, AkeruMemoryToolHandler>;
}
export interface AkeruToolRuntimeOptions {
@@ -30,7 +61,7 @@ export interface AkeruToolRuntimeOptions {
export interface AkeruToolExecution {
readonly threadId: string;
- readonly toolId: AkeruToolId;
+ readonly toolId: AkeruRuntimeToolId;
readonly toolCallId: string;
readonly input: unknown;
readonly approvalMode: "require-grant";
@@ -40,10 +71,10 @@ export interface AkeruToolRuntime {
readonly registerSession: (threadId: string, session: AkeruToolSession) => void;
readonly unregisterSession: (threadId: string) => void;
readonly clearApprovals: (threadId: string) => void;
- readonly toolsForThread: (threadId: string) => ReadonlyArray<AkeruToolDefinition>;
+ readonly toolsForThread: (threadId: string) => ReadonlyArray<AkeruRuntimeToolDefinition>;
readonly requiresApproval: (
threadId: string,
- toolId: AkeruToolId,
+ toolId: AkeruRuntimeToolId,
input: unknown,
) => Promise<boolean>;
readonly grantApproval: (input: Omit<AkeruToolExecution, "approvalMode">) => void;
@@ -114,7 +145,7 @@ function executable(value: unknown): value is {
export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): AkeruToolRuntime {
const sessions = new Map<string, AkeruToolSession>();
- const grants = new Map<string, { readonly toolId: AkeruToolId; readonly input: string }>();
+ const grants = new Map<string, { readonly toolId: AkeruRuntimeToolId; readonly input: string }>();
const key = (threadId: string, toolCallId: string) => `${threadId}\u0000${toolCallId}`;
const clearGrants = (threadId: string) => {
for (const grantKey of grants.keys()) {
@@ -151,20 +182,50 @@ export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): Akeru
const session = sessions.get(threadId);
if (!session) throw new Error(`Tool session '${threadId}' is not registered.`);
const implemented = implementedTools(session);
- return filterAkeruTools({
+ const workspaceTools = filterAkeruTools({
capabilities: new Set(["bot-workspace", "user-computer"]),
workspaceType: session.workspaceType,
hasUserComputer: Boolean(session.userComputerWorkspace),
localFullAccess: session.runtimeMode === "full-access",
implementedTools: implemented,
});
+ return session.memoryHandlers
+ ? [...workspaceTools, ...MEMORY_TOOL_DEFINITIONS]
+ : workspaceTools;
};
- const validatedInput = (toolId: AkeruToolId, input: unknown) =>
- Schema.decodeUnknownPromise(AkeruToolInputSchemas[toolId])(input, {
+ const validatedInput = (toolId: AkeruRuntimeToolId, input: unknown) =>
+ Schema.decodeUnknownPromise(
+ isMemoryToolId(toolId) ? AkeruMemoryToolInputSchemas[toolId] : AkeruToolInputSchemas[toolId],
+ )(input, {
onExcessProperty: "error",
});
+ const decodedGrantInput = (toolId: AkeruRuntimeToolId, input: unknown) =>
+ isMemoryToolId(toolId)
+ ? MEMORY_TOOL_INPUT_DECODERS[toolId](input, { onExcessProperty: "error" })
+ : decodeAkeruToolInput(toolId, input);
+
+ const requiresApproval = async (
+ session: AkeruToolSession,
+ tool: AkeruRuntimeToolDefinition,
+ input: unknown,
+ ) => {
+ if (tool.id === "recall_memory") return field(input, "includeSensitive") === true;
+ if (tool.id === "remember") {
+ return field(input, "scope") !== "private" || field(input, "sensitive") === true;
+ }
+ if (tool.id === "update_memory" || tool.id === "forget_memory") return true;
+ return akeruToolRequiresApproval(
+ tool as AkeruToolDefinition,
+ {
+ localFullAccess: session.runtimeMode === "full-access",
+ workspaceType: session.workspaceType,
+ },
+ input,
+ );
+ };
+
return {
registerSession: (threadId, session) => {
clearGrants(threadId);
@@ -181,19 +242,12 @@ export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): Akeru
if (!session) throw new Error(`Tool session '${threadId}' is not registered.`);
const tool = toolsForThread(threadId).find((candidate) => candidate.id === toolId);
if (!tool) throw new Error(`Tool '${toolId}' is not available for this turn.`);
- return akeruToolRequiresApproval(
- tool,
- {
- localFullAccess: session.runtimeMode === "full-access",
- workspaceType: session.workspaceType,
- },
- await validatedInput(toolId, input),
- );
+ return requiresApproval(session, tool, await validatedInput(toolId, input));
},
grantApproval: (input) => {
grants.set(key(input.threadId, input.toolCallId), {
toolId: input.toolId,
- input: canonicalInput(decodeAkeruToolInput(input.toolId, input.input)),
+ input: canonicalInput(decodedGrantInput(input.toolId, input.input)),
});
},
execute: async (input) => {
@@ -204,16 +258,7 @@ export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): Akeru
);
if (!tool) throw new Error(`Tool '${input.toolId}' is not available for this turn.`);
const decoded = await validatedInput(input.toolId, input.input);
- if (
- akeruToolRequiresApproval(
- tool,
- {
- localFullAccess: session.runtimeMode === "full-access",
- workspaceType: session.workspaceType,
- },
- decoded,
- )
- ) {
+ if (await requiresApproval(session, tool, decoded)) {
const grantKey = key(input.threadId, input.toolCallId);
const grant = grants.get(grantKey);
if (
@@ -227,6 +272,12 @@ export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): Akeru
grants.delete(grantKey);
}
+ if (isMemoryToolId(input.toolId)) {
+ const handler = session.memoryHandlers?.[input.toolId];
+ if (!handler) throw new Error(`Tool '${input.toolId}' has no backend.`);
+ return handler({ ...input, toolId: input.toolId, input: decoded });
+ }
+
if (input.toolId === "CopyToBox" || input.toolId === "CopyFromBox") {
const source =
input.toolId === "CopyToBox" ? session.userComputerWorkspace : session.workspace;
diff --git a/apps/server/src/provider/Layers/AgentController.test.ts b/apps/server/src/provider/Layers/AgentController.test.ts
index 648aa9bad..066f12e81 100644
--- a/apps/server/src/provider/Layers/AgentController.test.ts
+++ b/apps/server/src/provider/Layers/AgentController.test.ts
@@ -8,12 +8,15 @@ import type { AgentControllerEvent, MastraDBMessage, Session } from "@mastra/cor
import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";
import {
AKERU_PRODUCT_FEEDBACK_TOOL_NAME,
+ AkeruMemoryTenantId,
+ AkeruMemoryUserId,
ApprovalRequestId,
BotId,
EventId,
McpServerId,
ProviderDriverKind,
ProviderInstanceId,
+ ProjectId,
ThreadId,
TurnId,
type ProviderRuntimeEvent,
@@ -28,6 +31,8 @@ import { assert, describe, expect, vi } from "vite-plus/test";
import { ServerConfig } from "../../config.ts";
import { BotInboxService } from "../../bot-inbox/service.ts";
+import type { EntityMemoryRepositoryShape } from "../../memory/Services/EntityMemoryRepository.ts";
+import type { MemoryCandidateRepositoryShape } from "../../memory/Services/MemoryCandidateRepository.ts";
import { AgentController } from "../Services/AgentController.ts";
import { LegacyProviderBridge } from "../Services/LegacyProviderBridge.ts";
import type { ProviderServiceShape } from "../Services/ProviderService.ts";
@@ -213,10 +218,12 @@ function makeLayer(
factory: NonNullable<AgentControllerLiveOptions["makeMastraHarness"]>,
makeMcpManager?: NonNullable<AgentControllerLiveOptions["makeMcpManager"]>,
baseDir?: string,
+ memory?: Pick<AgentControllerLiveOptions, "entityMemoryRepository" | "memoryCandidateRepository">,
) {
return makeAgentControllerLive({
makeMastraHarness: factory,
...(makeMcpManager ? { makeMcpManager } : {}),
+ ...memory,
makeBotBrowser: () =>
({
tools: {},
@@ -243,9 +250,10 @@ function provideController<A, E>(
factory: NonNullable<AgentControllerLiveOptions["makeMastraHarness"]>,
makeMcpManager?: NonNullable<AgentControllerLiveOptions["makeMcpManager"]>,
baseDir?: string,
+ memory?: Pick<AgentControllerLiveOptions, "entityMemoryRepository" | "memoryCandidateRepository">,
) {
return effect.pipe(
- Effect.provide(makeLayer(bridge, factory, makeMcpManager, baseDir)),
+ Effect.provide(makeLayer(bridge, factory, makeMcpManager, baseDir, memory)),
Effect.orDie,
);
}
@@ -495,6 +503,103 @@ describe("AgentControllerLive", () => {
);
});
+ it.effect("registers repository-backed memory tools for Mastra sessions", () => {
+ const bridge = makeBridge();
+ const mastra = makeMastraHarness();
+ const access = {
+ tenantId: AkeruMemoryTenantId.make("local"),
+ userId: AkeruMemoryUserId.make("owner"),
+ threadId: codexThreadId,
+ projectId: ProjectId.make("project-memory-tools"),
+ workspaceRoot: "/workspace/memory-tools",
+ botId: BotId.make("bot-memory-tools"),
+ groupId: null,
+ respondingBotId: BotId.make("bot-memory-tools"),
+ groupMemberBotIds: [],
+ } as const;
+ const insert = vi.fn((input) => Effect.succeed(input.revision));
+ const create = vi.fn((input) => Effect.succeed(input.candidate));
+ const entityMemoryRepository = { insert } as unknown as EntityMemoryRepositoryShape;
+ const memoryCandidateRepository = { create } as unknown as MemoryCandidateRepositoryShape;
+
+ return provideController(
+ Effect.gen(function* () {
+ const controller = yield* AgentController;
+ yield* resolveCodex(controller);
+ yield* controller.startSession(codexThreadId, {
+ threadId: codexThreadId,
+ provider: ProviderDriverKind.make("codex"),
+ providerInstanceId: codexInstanceId,
+ modelSelection: codexSelection,
+ runtimeMode: "full-access",
+ memoryAccess: access,
+ });
+
+ const runtime = mastra.harnessOptions[0]?.toolRuntime;
+ assert.isDefined(runtime);
+ expect(runtime.toolsForThread(String(codexThreadId)).map((tool) => tool.id)).toEqual(
+ expect.arrayContaining(["recall_memory", "remember", "update_memory", "forget_memory"]),
+ );
+ yield* Effect.promise(() =>
+ runtime.execute({
+ threadId: String(codexThreadId),
+ toolId: "remember",
+ toolCallId: "private-memory",
+ input: { fact: "The user prefers vim.", scope: "private" },
+ approvalMode: "require-grant",
+ }),
+ );
+ const sharedMemory = {
+ threadId: String(codexThreadId),
+ toolId: "remember" as const,
+ toolCallId: "shared-memory",
+ input: { fact: "The project uses Bun.", scope: "project" },
+ approvalMode: "require-grant" as const,
+ };
+ runtime.grantApproval(sharedMemory);
+ yield* Effect.promise(() => runtime.execute(sharedMemory));
+
+ expect(insert).toHaveBeenCalledOnce();
+ expect(create).toHaveBeenCalledOnce();
+
+ const events: ProviderRuntimeEvent[] = [];
+ const eventsFiber = yield* controller.streamEvents.pipe(
+ Stream.runForEach((event) =>
+ Effect.sync(() => {
+ events.push(event);
+ }),
+ ),
+ Effect.forkChild({ startImmediately: true }),
+ );
+ yield* Effect.yieldNow;
+ yield* controller.sendTurn({ threadId: codexThreadId, input: "Remember this." });
+ mastra.emit({
+ type: "tool_approval_required",
+ toolCallId: "memory-approval",
+ toolName: "remember",
+ args: { fact: "The project uses Bun.", scope: "project" },
+ } as AgentControllerEvent);
+ yield* Effect.yieldNow;
+ expect(events.find((event) => event.type === "request.opened")).toMatchObject({
+ payload: {
+ options: [
+ { decision: "accept", label: "Allow" },
+ { decision: "decline", label: "Decline" },
+ ],
+ },
+ });
+ yield* controller.interruptTurn({ threadId: codexThreadId });
+ mastra.finishSend();
+ yield* Fiber.interrupt(eventsFiber);
+ }),
+ bridge.service,
+ mastra.factory,
+ undefined,
+ undefined,
+ { entityMemoryRepository, memoryCandidateRepository },
+ );
+ });
+
it.effect("boots a real Mastra Code controller and creates a Codex session", () => {
const bridge = makeBridge();
const layer = makeAgentControllerLive().pipe(
diff --git a/apps/server/src/provider/Layers/AgentController.ts b/apps/server/src/provider/Layers/AgentController.ts
index 612ad321a..d936154da 100644
--- a/apps/server/src/provider/Layers/AgentController.ts
+++ b/apps/server/src/provider/Layers/AgentController.ts
@@ -28,6 +28,7 @@ import {
type RuntimeMode,
type ThreadId,
AKERU_PRODUCT_FEEDBACK_TOOL_NAME,
+ type AkeruMemoryThreadAccess,
} from "@t3tools/contracts";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
@@ -39,6 +40,15 @@ import { resolveAttachmentPath } from "../../attachmentStore.ts";
import { BotInboxService } from "../../bot-inbox/service.ts";
import { recordUserActionIncident } from "../../bot-inbox/userActionIncidents.ts";
import { ServerConfig } from "../../config.ts";
+import { createMemoryToolHandlers } from "../../memory/MemoryToolHandlers.ts";
+import {
+ EntityMemoryRepository,
+ type EntityMemoryRepositoryShape,
+} from "../../memory/Services/EntityMemoryRepository.ts";
+import {
+ MemoryCandidateRepository,
+ type MemoryCandidateRepositoryShape,
+} from "../../memory/Services/MemoryCandidateRepository.ts";
import {
SubscriptionAuthService,
type SubscriptionProviderId,
@@ -51,7 +61,11 @@ import {
type AkeruMastraHarnessOptions,
type AkeruMastraSession,
} from "../AkeruMastraHarness.ts";
-import { createAkeruToolRuntime, type AkeruToolSession } from "../AkeruToolRuntime.ts";
+import {
+ createAkeruToolRuntime,
+ isMemoryToolId,
+ type AkeruToolSession,
+} from "../AkeruToolRuntime.ts";
import type { BotBrowser, BotBrowserAttachment, CreateBotBrowserInput } from "../botBrowser.ts";
import { AkeruSessionResources } from "../AkeruSessionResources.ts";
import type { CreateRemoteBotWorkspaceInput } from "../botWorkspace.ts";
@@ -110,6 +124,8 @@ export interface AgentControllerLiveOptions {
readonly makeMcpManager?: typeof createMcpManager;
readonly makeRemoteWorkspace?: (input: CreateRemoteBotWorkspaceInput) => Promise<Workspace>;
readonly makeBotBrowser?: (input: CreateBotBrowserInput) => BotBrowser;
+ readonly entityMemoryRepository?: EntityMemoryRepositoryShape;
+ readonly memoryCandidateRepository?: MemoryCandidateRepositoryShape;
}
export function createAkeruMastraAuthStorage(secretsDir: string): AuthStorage {
@@ -303,6 +319,14 @@ const make = (options?: AgentControllerLiveOptions) =>
recordUserActionIncident(botInbox, input);
},
});
+ const memoryHandlers = (access: AkeruMemoryThreadAccess | undefined) =>
+ access && options?.entityMemoryRepository && options.memoryCandidateRepository
+ ? createMemoryToolHandlers(
+ options.entityMemoryRepository,
+ options.memoryCandidateRepository,
+ access,
+ )
+ : undefined;
const legacyResourceIdentity = new Map<
string,
{
@@ -530,6 +554,7 @@ const make = (options?: AgentControllerLiveOptions) =>
{ decision: "decline", label: "Cancel" },
]
: AKERU_TOOL_CATALOG.some((tool) => tool.id === event.toolName) ||
+ isMemoryToolId(event.toolName) ||
akeruActionNeedsApproval(event.toolName, event.args)
? [
{ decision: "accept", label: "Allow" },
@@ -696,11 +721,14 @@ const make = (options?: AgentControllerLiveOptions) =>
const toolSession = { ...existing.toolSession };
delete toolSession.botId;
delete toolSession.botName;
+ delete toolSession.memoryHandlers;
+ const nextMemoryHandlers = memoryHandlers(input.memoryAccess);
existing.toolSession = {
...toolSession,
runtimeMode: input.runtimeMode,
...(input.botId ? { botId: input.botId } : {}),
...(input.botName ? { botName: input.botName } : {}),
+ ...(nextMemoryHandlers ? { memoryHandlers: nextMemoryHandlers } : {}),
};
toolRuntime.registerSession(key, existing.toolSession);
return toProviderSession(threadId, existing);
@@ -769,6 +797,7 @@ const make = (options?: AgentControllerLiveOptions) =>
),
);
}
+ const registeredMemoryHandlers = memoryHandlers(input.memoryAccess);
const toolSession: AkeruToolSession = {
...(input.botId ? { botId: input.botId } : {}),
...(input.botName ? { botName: input.botName } : {}),
@@ -778,6 +807,7 @@ const make = (options?: AgentControllerLiveOptions) =>
...(resources.userComputerWorkspace
? { userComputerWorkspace: resources.userComputerWorkspace }
: {}),
+ ...(registeredMemoryHandlers ? { memoryHandlers: registeredMemoryHandlers } : {}),
};
toolRuntime.registerSession(key, toolSession);
const session = yield* runMastra("createSession", () =>
@@ -999,17 +1029,18 @@ const make = (options?: AgentControllerLiveOptions) =>
active.approvalRequests.delete(toolCallId);
const { name: toolName, input: toolInput } = toolRequest;
const akeruTool = AKERU_TOOL_CATALOG.find((tool) => tool.id === toolName);
- if (akeruTool && input.decision !== "decline" && input.decision !== "cancel") {
+ const runtimeToolId = akeruTool?.id ?? (isMemoryToolId(toolName) ? toolName : undefined);
+ if (runtimeToolId && input.decision !== "decline" && input.decision !== "cancel") {
toolRuntime.grantApproval({
threadId: key,
toolCallId,
- toolId: akeruTool.id,
+ toolId: runtimeToolId,
input: toolInput,
});
}
if (
input.decision === "acceptForSession" &&
- !akeruTool &&
+ !runtimeToolId &&
!akeruActionNeedsApproval(toolName, toolInput) &&
toolName !== AKERU_PRODUCT_FEEDBACK_TOOL_NAME
) {
@@ -1022,7 +1053,7 @@ const make = (options?: AgentControllerLiveOptions) =>
active.session.respondToToolApproval({
toolCallId,
decision:
- akeruTool && input.decision !== "decline" && input.decision !== "cancel"
+ runtimeToolId && input.decision !== "decline" && input.decision !== "cancel"
? "approve"
: approvalDecision(input.decision),
});
@@ -1220,4 +1251,11 @@ function toProviderSession(threadId: ThreadId, active: ActiveSession): ProviderS
export const makeAgentControllerLive = (options?: AgentControllerLiveOptions) =>
Layer.effect(AgentController, make(options));
-export const AgentControllerLive = makeAgentControllerLive();
+export const AgentControllerLive = Layer.effect(
+ AgentController,
+ Effect.gen(function* () {
+ const entityMemoryRepository = yield* EntityMemoryRepository;
+ const memoryCandidateRepository = yield* MemoryCandidateRepository;
+ return yield* make({ entityMemoryRepository, memoryCandidateRepository });
+ }),
+);
diff --git a/apps/server/src/provider/Services/AgentController.ts b/apps/server/src/provider/Services/AgentController.ts
index 52d5cd792..8ef79cb29 100644
--- a/apps/server/src/provider/Services/AgentController.ts
+++ b/apps/server/src/provider/Services/AgentController.ts
@@ -1,5 +1,6 @@
import type {
AkeruConversationMemorySnapshot,
+ AkeruMemoryThreadAccess,
BotEngine,
ModelSelection,
ProviderInteractionMode,
@@ -58,7 +59,7 @@ export interface AgentControllerShape {
readonly startSession: (
threadId: ThreadId,
- input: ProviderSessionStartInput,
+ input: ProviderSessionStartInput & { readonly memoryAccess?: AkeruMemoryThreadAccess },
) => Effect.Effect<ProviderSession, AgentControllerError>;
readonly sendTurn: (