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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+ },+ };+}