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(server): add memory tool handlers (#41)

Leob16dd5933dc1
diff --git a/apps/server/src/memory/MemoryToolHandlers.test.ts b/apps/server/src/memory/MemoryToolHandlers.test.ts
new file mode 100644
index 000000000..403fb6f83
--- /dev/null
+++ b/apps/server/src/memory/MemoryToolHandlers.test.ts
@@ -0,0 +1,297 @@
+import { assert, it } from "@effect/vitest";
+import {
+ AkeruMemoryCandidateId,
+ AkeruMemoryRootId,
+ AkeruMemoryTenantId,
+ AkeruMemoryUserId,
+ BotId,
+ ProjectId,
+ ThreadId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+
+import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";
+import { EntityMemoryRepositoryLive } from "./Layers/EntityMemoryRepository.ts";
+import { MemoryCandidateRepositoryLive } from "./Layers/MemoryCandidateRepository.ts";
+import {
+ createMemoryToolHandlers,
+ decideMemoryCandidate,
+ type AkeruMemoryToolHandler,
+ type AkeruMemoryToolId,
+} from "./MemoryToolHandlers.ts";
+import { EntityMemoryRepository } from "./Services/EntityMemoryRepository.ts";
+import { MemoryCandidateRepository } from "./Services/MemoryCandidateRepository.ts";
+import { MemoryRevisionWriteLockLive } from "./Services/MemoryRevisionWriteLock.ts";
+
+const repositoriesLive = Layer.mergeAll(
+ EntityMemoryRepositoryLive,
+ MemoryCandidateRepositoryLive,
+).pipe(Layer.provide(MemoryRevisionWriteLockLive));
+
+const layer = Layer.mergeAll(
+ repositoriesLive.pipe(Layer.provide(SqlitePersistenceMemory)),
+ SqlitePersistenceMemory,
+);
+
+const access = {
+ tenantId: AkeruMemoryTenantId.make("local"),
+ userId: AkeruMemoryUserId.make("owner"),
+ threadId: ThreadId.make("thread-memory-tools"),
+ projectId: ProjectId.make("project-memory-tools"),
+ workspaceRoot: "/workspace/memory-tools",
+ botId: BotId.make("bot-memory-tools"),
+ groupId: null,
+ respondingBotId: null,
+ groupMemberBotIds: [],
+} as const;
+
+const execute = (toolId: AkeruMemoryToolId, handler: AkeruMemoryToolHandler, input: unknown) =>
+ handler({
+ threadId: access.threadId,
+ toolId,
+ toolCallId: `call-${toolId}`,
+ input,
+ approvalMode: "require-grant",
+ });
+
+it.layer(layer)("MemoryToolHandlers", (it) => {
+ it.effect("writes private facts directly without creating an approval orphan", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ const handlers = createMemoryToolHandlers(repository, candidates, access);
+
+ const saved = yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "The user prefers Vim.",
+ scope: "private",
+ }),
+ );
+
+ assert.equal((saved as { revision: number }).revision, 1);
+ assert.deepEqual(yield* candidates.listPending({ access }), []);
+ assert.equal((yield* repository.listCurrent({ access })).length, 1);
+ }),
+ );
+
+ it.effect("leaves shared and sensitive saves pending with no current revision", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ const handlers = createMemoryToolHandlers(repository, candidates, access);
+ const currentCount = (yield* repository.listCurrent({ access })).length;
+ const pendingCount = (yield* candidates.listPending({ access })).length;
+
+ yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "The project uses Bun.",
+ scope: "project",
+ }),
+ );
+ yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "The private token is alpha.",
+ scope: "private",
+ sensitive: true,
+ }),
+ );
+
+ assert.equal((yield* candidates.listPending({ access })).length, pendingCount + 2);
+ assert.equal((yield* repository.listCurrent({ access })).length, currentCount);
+ }),
+ );
+
+ it.effect("updates private non-sensitive facts directly", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ let invalidations = 0;
+ const handlers = createMemoryToolHandlers(repository, candidates, access, () => {
+ invalidations += 1;
+ });
+ const pendingCount = (yield* candidates.listPending({ access })).length;
+ const saved = (yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "Use npm.",
+ scope: "private",
+ }),
+ )) as { rootId: string };
+
+ const updated = (yield* Effect.promise(() =>
+ execute("update_memory", handlers.update_memory, {
+ memoryId: saved.rootId,
+ expectedRevision: 1,
+ fact: "Use Bun.",
+ scope: "private",
+ }),
+ )) as { fact: string; revision: number };
+
+ assert.equal(updated.fact, "Use Bun.");
+ assert.equal(updated.revision, 2);
+ assert.equal(invalidations, 1);
+ assert.equal((yield* candidates.listPending({ access })).length, pendingCount);
+ }),
+ );
+
+ it.effect("approves or rejects each candidate once", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ const handlers = createMemoryToolHandlers(repository, candidates, access);
+ const currentCount = (yield* repository.listCurrent({ access })).length;
+ const pendingCount = (yield* candidates.listPending({ access })).length;
+ const approvedCandidate = (yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "The project uses Bun.",
+ scope: "project",
+ }),
+ )) as { candidateId: string };
+ const rejectedCandidate = (yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "Temporary note.",
+ scope: "project",
+ }),
+ )) as { candidateId: string };
+
+ const approved = yield* Effect.promise(() =>
+ decideMemoryCandidate(repository, candidates, access, {
+ candidateId: AkeruMemoryCandidateId.make(approvedCandidate.candidateId),
+ decision: "approve",
+ }),
+ );
+ const rejected = yield* Effect.promise(() =>
+ decideMemoryCandidate(repository, candidates, access, {
+ candidateId: AkeruMemoryCandidateId.make(rejectedCandidate.candidateId),
+ decision: "reject",
+ }),
+ );
+
+ assert.equal(approved.status, "approved");
+ assert.equal(rejected.status, "rejected");
+ assert.equal((yield* repository.listCurrent({ access })).length, currentCount + 1);
+ assert.equal((yield* candidates.listPending({ access })).length, pendingCount);
+ const repeated = yield* Effect.promise(() =>
+ decideMemoryCandidate(repository, candidates, access, {
+ candidateId: AkeruMemoryCandidateId.make(approvedCandidate.candidateId),
+ decision: "approve",
+ }).then(
+ () => false,
+ () => true,
+ ),
+ );
+ assert.isTrue(repeated);
+ }),
+ );
+
+ it.effect("keeps a pending update at its expected revision until approval", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ let invalidations = 0;
+ const handlers = createMemoryToolHandlers(repository, candidates, access, () => {
+ invalidations += 1;
+ });
+ const saved = (yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "Use npm.",
+ scope: "private",
+ }),
+ )) as { rootId: string };
+ const pending = (yield* Effect.promise(() =>
+ execute("update_memory", handlers.update_memory, {
+ memoryId: saved.rootId,
+ expectedRevision: 1,
+ fact: "Use Bun.",
+ scope: "project",
+ }),
+ )) as { candidateId: string };
+
+ const before = yield* repository.getCurrent({
+ access,
+ rootId: AkeruMemoryRootId.make(saved.rootId),
+ });
+ assert.equal(before.revision, 1);
+ assert.equal(invalidations, 0);
+ yield* Effect.promise(() =>
+ decideMemoryCandidate(
+ repository,
+ candidates,
+ access,
+ {
+ candidateId: AkeruMemoryCandidateId.make(pending.candidateId),
+ decision: "approve",
+ },
+ () => {
+ invalidations += 1;
+ },
+ ),
+ );
+ const after = yield* repository.getCurrent({
+ access,
+ rootId: AkeruMemoryRootId.make(saved.rootId),
+ });
+ assert.equal(after.revision, 2);
+ assert.equal(after.fact, "Use Bun.");
+ assert.equal(invalidations, 1);
+ }),
+ );
+
+ it.effect("routes forget OCC through tombstone", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ const handlers = createMemoryToolHandlers(repository, candidates, access);
+ const saved = (yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "Forget this.",
+ scope: "private",
+ }),
+ )) as { rootId: string };
+
+ const stale = yield* Effect.promise(() =>
+ execute("forget_memory", handlers.forget_memory, {
+ memoryId: saved.rootId,
+ expectedRevision: 2,
+ }).then(
+ () => false,
+ () => true,
+ ),
+ );
+ assert.isTrue(stale);
+ const current = yield* repository.getCurrent({
+ access,
+ rootId: AkeruMemoryRootId.make(saved.rootId),
+ });
+ assert.equal(current.deletionState, "active");
+ }),
+ );
+
+ it.effect("propagates candidate creation failures", () =>
+ Effect.gen(function* () {
+ const repository = yield* EntityMemoryRepository;
+ const candidates = yield* MemoryCandidateRepository;
+ const currentCount = (yield* repository.listCurrent({ access })).length;
+ const handlers = createMemoryToolHandlers(
+ repository,
+ {
+ ...candidates,
+ create: () => Effect.die(new Error("candidate write failed")),
+ },
+ access,
+ );
+
+ const failed = yield* Effect.promise(() =>
+ execute("remember", handlers.remember, {
+ fact: "The project uses Bun.",
+ scope: "project",
+ }).then(
+ () => false,
+ (error) => String(error).includes("candidate write failed"),
+ ),
+ );
+ assert.isTrue(failed);
+ assert.equal((yield* repository.listCurrent({ access })).length, currentCount);
+ }),
+ );
+});
diff --git a/apps/server/src/memory/MemoryToolHandlers.ts b/apps/server/src/memory/MemoryToolHandlers.ts
new file mode 100644
index 000000000..72bd2dfc6
--- /dev/null
+++ b/apps/server/src/memory/MemoryToolHandlers.ts
@@ -0,0 +1,350 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeCrypto from "node:crypto";
+
+import {
+ AkeruMemoryCandidateId,
+ AkeruMemoryEntityId,
+ AkeruMemoryId,
+ AkeruMemoryRootId,
+ type AkeruMemoryCandidateDecision,
+ type AkeruMemoryDecisionReceipt,
+ type AkeruMemoryRevision,
+ type AkeruMemoryScope,
+ type AkeruMemoryTargetScope,
+ type AkeruMemoryThreadAccess,
+} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+
+import type { AkeruToolExecution } from "../provider/AkeruToolRuntime.ts";
+import { deriveAkeruWorkspaceId, resolveAuthorizedMemoryPartitions } from "./EntityMemoryAccess.ts";
+import type { EntityMemoryRepositoryShape } from "./Services/EntityMemoryRepository.ts";
+import type { MemoryCandidateRepositoryShape } from "./Services/MemoryCandidateRepository.ts";
+
+export type AkeruMemoryToolId = "recall_memory" | "remember" | "update_memory" | "forget_memory";
+
+export type AkeruMemoryToolHandler = (
+ input: Omit<AkeruToolExecution, "toolId"> & { readonly toolId: AkeruMemoryToolId },
+) => Promise<unknown>;
+
+type PendingUpdate = {
+ readonly rootId: AkeruMemoryRootId;
+ readonly expectedRevision: number;
+};
+
+const pendingUpdates = new WeakMap<MemoryCandidateRepositoryShape, Map<string, PendingUpdate>>();
+
+const nowIso = () => DateTime.formatIso(DateTime.nowUnsafe());
+
+function field(input: unknown, name: string): unknown {
+ return typeof input === "object" && input !== null
+ ? Object.getOwnPropertyDescriptor(input, name)?.value
+ : undefined;
+}
+
+function stringField(input: unknown, name: string): string {
+ const value = field(input, name);
+ if (typeof value !== "string" || value.length === 0) {
+ throw new Error(`Memory tool field '${name}' is required.`);
+ }
+ return value;
+}
+
+function expectedRevision(input: unknown): number {
+ const value = field(input, "expectedRevision");
+ if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+ throw new Error("Memory tool field 'expectedRevision' must be a positive integer.");
+ }
+ return value;
+}
+
+function targetScope(input: unknown): AkeruMemoryTargetScope {
+ const scope = stringField(input, "scope");
+ if (
+ scope === "private" ||
+ scope === "bot" ||
+ scope === "project" ||
+ scope === "group" ||
+ scope === "workspace"
+ ) {
+ return scope;
+ }
+ throw new Error(`Memory scope '${scope}' is not supported.`);
+}
+
+const storedScope = (scope: AkeruMemoryTargetScope): AkeruMemoryScope =>
+ scope === "private" ? "bot-user" : scope;
+
+function entityFor(scope: AkeruMemoryScope, access: AkeruMemoryThreadAccess) {
+ switch (scope) {
+ case "bot-user":
+ case "user":
+ return { entityKind: "user" as const, entityId: AkeruMemoryEntityId.make(access.userId) };
+ case "bot":
+ if (access.botId === null) throw new Error("This thread has no private bot identity.");
+ return { entityKind: "bot" as const, entityId: AkeruMemoryEntityId.make(access.botId) };
+ case "project":
+ return {
+ entityKind: "project" as const,
+ entityId: AkeruMemoryEntityId.make(access.projectId),
+ };
+ case "group":
+ if (access.groupId === null) throw new Error("This thread is not in a group.");
+ return { entityKind: "group" as const, entityId: AkeruMemoryEntityId.make(access.groupId) };
+ case "workspace":
+ return {
+ entityKind: "workspace" as const,
+ entityId: AkeruMemoryEntityId.make(deriveAkeruWorkspaceId(access.workspaceRoot)),
+ };
+ case "thread":
+ return { entityKind: "other" as const, entityId: AkeruMemoryEntityId.make(access.threadId) };
+ }
+}
+
+async function partitionFor(scope: AkeruMemoryTargetScope, access: AkeruMemoryThreadAccess) {
+ const wanted = storedScope(scope);
+ const partitions = await Effect.runPromise(resolveAuthorizedMemoryPartitions(access));
+ const partition = partitions.find((candidate) => candidate.scope === wanted);
+ if (!partition) throw new Error(`Memory scope '${scope}' is not available to this thread.`);
+ return partition;
+}
+
+const affectedBotIds = (access: AkeruMemoryThreadAccess) =>
+ access.groupId !== null
+ ? [...access.groupMemberBotIds]
+ : access.botId === null
+ ? []
+ : [access.botId];
+
+async function revisionFor(
+ access: AkeruMemoryThreadAccess,
+ scope: AkeruMemoryTargetScope,
+ fact: string,
+ sensitive: boolean,
+ now: string,
+ current?: AkeruMemoryRevision,
+) {
+ const partition = await partitionFor(scope, access);
+ return {
+ ...current,
+ id: AkeruMemoryId.make(NodeCrypto.randomUUID()),
+ rootId: current?.rootId ?? AkeruMemoryRootId.make(NodeCrypto.randomUUID()),
+ revision: current === undefined ? 1 : current.revision + 1,
+ partition,
+ ...entityFor(partition.scope, access),
+ kind: current?.kind ?? "fact",
+ value: current?.value ?? {},
+ fact,
+ sourceThreadId: current?.sourceThreadId ?? access.threadId,
+ sourceMessageId: current?.sourceMessageId ?? null,
+ authorBotId: current?.authorBotId ?? access.respondingBotId ?? access.botId,
+ initiatingUserId: current?.initiatingUserId ?? access.userId,
+ createdAt: current?.createdAt ?? now,
+ confirmedAt: now,
+ updatedAt: now,
+ confidence: current?.confidence ?? 1,
+ approvalState: "approved" as const,
+ supersedesId: current?.id ?? null,
+ supersededById: null,
+ visibility: partition.visibility,
+ deletionState: "active" as const,
+ pinned: current?.pinned ?? false,
+ sensitive,
+ affectedBotIds: affectedBotIds(access),
+ } satisfies AkeruMemoryRevision;
+}
+
+function rememberPendingUpdate(
+ candidates: MemoryCandidateRepositoryShape,
+ candidateId: string,
+ update: PendingUpdate,
+) {
+ const updates = pendingUpdates.get(candidates) ?? new Map<string, PendingUpdate>();
+ updates.set(candidateId, update);
+ pendingUpdates.set(candidates, updates);
+}
+
+export async function decideMemoryCandidate(
+ repository: EntityMemoryRepositoryShape,
+ candidates: MemoryCandidateRepositoryShape,
+ access: AkeruMemoryThreadAccess,
+ decision: AkeruMemoryCandidateDecision,
+ invalidateDerivedMemory?: (input: {
+ readonly rootId: AkeruMemoryRootId;
+ readonly affectedBotIds: ReadonlyArray<string>;
+ }) => void | Promise<void>,
+): Promise<AkeruMemoryDecisionReceipt> {
+ const candidate = (await Effect.runPromise(candidates.listPending({ access }))).find(
+ (item) => item.candidateId === decision.candidateId,
+ );
+ if (!candidate) throw new Error("The memory candidate is missing or already decided.");
+ const decidedAt = nowIso();
+ if (decision.decision === "reject") {
+ const receipt = await Effect.runPromise(
+ candidates.reject({
+ access,
+ candidateId: candidate.candidateId,
+ receiptId: `memory-${NodeCrypto.randomUUID()}`,
+ decidedAt,
+ }),
+ );
+ pendingUpdates.get(candidates)?.delete(candidate.candidateId);
+ return receipt;
+ }
+
+ const update = pendingUpdates.get(candidates)?.get(candidate.candidateId);
+ const current =
+ update === undefined
+ ? undefined
+ : await Effect.runPromise(repository.getCurrent({ access, rootId: update.rootId }));
+ if (current !== undefined && current.revision !== update?.expectedRevision) {
+ throw new Error(`Memory revision ${update?.expectedRevision} is stale.`);
+ }
+ const revision = await revisionFor(
+ access,
+ decision.scope ?? candidate.scope,
+ decision.fact ?? candidate.fact,
+ candidate.sensitive,
+ decidedAt,
+ current,
+ );
+ const receipt = await Effect.runPromise(
+ candidates.approve({
+ access,
+ candidateId: candidate.candidateId,
+ revision,
+ receiptId: `memory-${NodeCrypto.randomUUID()}`,
+ decidedAt,
+ }),
+ );
+ pendingUpdates.get(candidates)?.delete(candidate.candidateId);
+ if (current !== undefined) {
+ await invalidateDerivedMemory?.({
+ rootId: revision.rootId,
+ affectedBotIds: revision.affectedBotIds,
+ });
+ }
+ return receipt;
+}
+
+export function createMemoryToolHandlers(
+ repository: EntityMemoryRepositoryShape,
+ candidates: MemoryCandidateRepositoryShape,
+ access: AkeruMemoryThreadAccess,
+ invalidateDerivedMemory?: (input: {
+ readonly rootId: AkeruMemoryRootId;
+ readonly affectedBotIds: ReadonlyArray<string>;
+ }) => void | Promise<void>,
+): Record<AkeruMemoryToolId, AkeruMemoryToolHandler> {
+ const createCandidate = async (
+ fact: string,
+ scope: AkeruMemoryTargetScope,
+ sensitive: boolean,
+ now: string,
+ ) => {
+ const candidateId = AkeruMemoryCandidateId.make(NodeCrypto.randomUUID());
+ return Effect.runPromise(
+ candidates.create({
+ access,
+ candidate: {
+ candidateId,
+ tenantId: access.tenantId,
+ initiatingUserId: access.userId,
+ sourceThreadId: access.threadId,
+ sourceMessageId: null,
+ authorBotId: access.respondingBotId ?? access.botId,
+ fact,
+ scope,
+ sensitive,
+ confidence: 1,
+ affectedBotIds: affectedBotIds(access),
+ status: "pending",
+ createdAt: now,
+ decidedAt: null,
+ decidedMemoryRootId: null,
+ },
+ }),
+ );
+ };
+
+ return {
+ recall_memory: async ({ input }) => {
+ const rows = await Effect.runPromise(
+ repository.search({
+ access,
+ query: stringField(input, "query"),
+ limit: typeof field(input, "limit") === "number" ? Number(field(input, "limit")) : 10,
+ }),
+ );
+ const includeSensitive = field(input, "includeSensitive") === true;
+ return rows
+ .filter((revision) => includeSensitive || !revision.sensitive)
+ .map((revision) => ({
+ memoryId: revision.rootId,
+ expectedRevision: revision.revision,
+ scope: revision.partition.scope,
+ kind: revision.kind,
+ fact: revision.fact,
+ sensitive: revision.sensitive,
+ updatedAt: revision.updatedAt,
+ }));
+ },
+ remember: async ({ input }) => {
+ const scope = targetScope(input);
+ const sensitive = field(input, "sensitive") === true;
+ const fact = stringField(input, "fact");
+ const now = nowIso();
+ if (scope !== "private" || sensitive) return createCandidate(fact, scope, sensitive, now);
+ return Effect.runPromise(
+ repository.insert({
+ access,
+ revision: await revisionFor(access, scope, fact, false, now),
+ }),
+ );
+ },
+ update_memory: async ({ input }) => {
+ const rootId = AkeruMemoryRootId.make(stringField(input, "memoryId"));
+ const expected = expectedRevision(input);
+ const current = await Effect.runPromise(repository.getCurrent({ access, rootId }));
+ const scope = targetScope(input);
+ const sensitive =
+ typeof field(input, "sensitive") === "boolean"
+ ? field(input, "sensitive") === true
+ : current.sensitive;
+ const fact = stringField(input, "fact");
+ const now = nowIso();
+ if (scope !== "private" || sensitive) {
+ const candidate = await createCandidate(fact, scope, sensitive, now);
+ rememberPendingUpdate(candidates, candidate.candidateId, {
+ rootId,
+ expectedRevision: expected,
+ });
+ return candidate;
+ }
+ const revision = await revisionFor(access, scope, fact, false, now, current);
+ const saved = await Effect.runPromise(
+ repository.revise({
+ access,
+ expectedRevision: expected,
+ revision,
+ }),
+ );
+ await invalidateDerivedMemory?.({ rootId, affectedBotIds: saved.affectedBotIds });
+ return saved;
+ },
+ forget_memory: async ({ input }) => {
+ const rootId = AkeruMemoryRootId.make(stringField(input, "memoryId"));
+ const tombstone = await Effect.runPromise(
+ repository.tombstone({
+ access,
+ rootId,
+ expectedRevision: expectedRevision(input),
+ memoryId: AkeruMemoryId.make(NodeCrypto.randomUUID()),
+ updatedAt: nowIso(),
+ }),
+ );
+ await invalidateDerivedMemory?.({ rootId, affectedBotIds: tombstone.affectedBotIds });
+ return tombstone;
+ },
+ };
+}