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(contracts): define Akeru memory and usage records (#22)

Leoaadd9bcd2409
diff --git a/packages/contracts/src/akeruMemory.test.ts b/packages/contracts/src/akeruMemory.test.ts
new file mode 100644
index 000000000..22cf75f50
--- /dev/null
+++ b/packages/contracts/src/akeruMemory.test.ts
@@ -0,0 +1,180 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import {
+ AKERU_MEMORY_PACKET_MAX_CHARS,
+ AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS,
+ AKERU_MEMORY_PACKET_MAX_FACTS,
+ AkeruMemoryCandidate,
+ AkeruMemoryCandidateDecision,
+ AkeruMemoryDecisionReceipt,
+ AkeruMemoryPacket,
+ AkeruMemoryMutateInput,
+ AkeruMemoryRevision,
+} from "./akeruMemory.ts";
+
+const revision = {
+ id: "memory-1",
+ rootId: "root-1",
+ revision: 1,
+ partition: { tenantId: "tenant-1", scope: "bot-user", partitionId: "bot-1:user-1" },
+ entityKind: "user",
+ entityId: "user-1",
+ kind: "preference",
+ value: { theme: "dark" },
+ fact: "The user prefers dark themes.",
+ sourceThreadId: "thread-1",
+ sourceMessageId: "message-1",
+ authorBotId: "bot-1",
+ initiatingUserId: "user-1",
+ createdAt: "2026-08-30T21:00:00.000Z",
+ confirmedAt: "2026-08-30T21:00:00.000Z",
+ updatedAt: "2026-08-30T21:00:00.000Z",
+ confidence: 0.9,
+ approvalState: "approved",
+ supersedesId: null,
+ supersededById: null,
+ visibility: "private",
+ deletionState: "active",
+ pinned: false,
+ sensitive: false,
+ affectedBotIds: ["bot-1"],
+} as const;
+
+describe("Akeru memory contracts", () => {
+ it.effect("decodes a complete immutable memory revision", () =>
+ Effect.gen(function* () {
+ const decoded = yield* Schema.decodeUnknownEffect(AkeruMemoryRevision)(revision);
+ assert.equal(decoded.partition.scope, "bot-user");
+ assert.equal(decoded.value.theme, "dark");
+ }),
+ );
+
+ it.effect("rejects confidence outside the supported range", () =>
+ Effect.gen(function* () {
+ const exit = yield* Schema.decodeUnknownEffect(AkeruMemoryRevision)({
+ ...revision,
+ confidence: 1.01,
+ }).pipe(Effect.exit);
+ assert.isTrue(exit._tag === "Failure");
+ }),
+ );
+
+ it.effect("types pending candidates and editable approval decisions", () =>
+ Effect.gen(function* () {
+ const candidate = yield* Schema.decodeUnknownEffect(AkeruMemoryCandidate)({
+ candidateId: "candidate-1",
+ tenantId: "tenant-1",
+ initiatingUserId: "user-1",
+ sourceThreadId: "thread-1",
+ sourceMessageId: "message-1",
+ authorBotId: "bot-1",
+ fact: "The project uses Bun.",
+ scope: "project",
+ sensitive: false,
+ confidence: 0.9,
+ affectedBotIds: ["bot-1", "bot-2"],
+ status: "pending",
+ createdAt: "2026-08-30T21:00:00.000Z",
+ decidedAt: null,
+ decidedMemoryRootId: null,
+ });
+ const decision = yield* Schema.decodeUnknownEffect(AkeruMemoryCandidateDecision)({
+ candidateId: candidate.candidateId,
+ decision: "approve",
+ fact: "The project uses Bun 2.",
+ scope: "workspace",
+ });
+
+ assert.equal(candidate.status, "pending");
+ assert.equal(decision.decision, "approve");
+ }),
+ );
+
+ it.effect("requires rejected decisions and durable receipts to identify the candidate", () =>
+ Effect.gen(function* () {
+ const rejected = yield* Schema.decodeUnknownEffect(AkeruMemoryCandidateDecision)({
+ candidateId: "candidate-1",
+ decision: "reject",
+ });
+ const receipt = yield* Schema.decodeUnknownEffect(AkeruMemoryDecisionReceipt)({
+ candidateId: "candidate-1",
+ status: "rejected",
+ fact: "Do not save this.",
+ scope: "private",
+ affectedBotIds: ["bot-1"],
+ memoryRootId: null,
+ createdAt: "2026-08-30T21:00:00.000Z",
+ });
+
+ assert.equal(rejected.decision, "reject");
+ assert.isNull(receipt.memoryRootId);
+ }),
+ );
+
+ it.effect("enforces all provider memory packet bounds", () =>
+ Effect.gen(function* () {
+ const fact = {
+ memoryId: "memory-1",
+ expectedRevision: 1,
+ scope: "user",
+ kind: "fact",
+ fact: "A fact",
+ pinned: false,
+ confidence: 1,
+ updatedAt: "2026-08-30T21:00:00.000Z",
+ } as const;
+ const decode = Schema.decodeUnknownEffect(AkeruMemoryPacket);
+ const tooManyFacts = yield* decode({
+ threadId: "thread-1",
+ facts: Array.from({ length: AKERU_MEMORY_PACKET_MAX_FACTS + 1 }, () => fact),
+ estimatedTokens: 1,
+ rendered: "memory",
+ }).pipe(Effect.exit);
+ const tooManyTokens = yield* decode({
+ threadId: "thread-1",
+ facts: [fact],
+ estimatedTokens: AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS + 1,
+ rendered: "memory",
+ }).pipe(Effect.exit);
+ const tooManyChars = yield* decode({
+ threadId: "thread-1",
+ facts: [fact],
+ estimatedTokens: 1,
+ rendered: "x".repeat(AKERU_MEMORY_PACKET_MAX_CHARS + 1),
+ }).pipe(Effect.exit);
+
+ assert.isTrue(tooManyFacts._tag === "Failure");
+ assert.isTrue(tooManyTokens._tag === "Failure");
+ assert.isTrue(tooManyChars._tag === "Failure");
+ }),
+ );
+
+ it.effect("decodes allowlisted memory mutations and rejects extra fields", () =>
+ Effect.gen(function* () {
+ const decode = Schema.decodeUnknownEffect(AkeruMemoryMutateInput);
+ const edit = yield* decode({
+ threadId: "thread-1",
+ mutation: {
+ operation: "fact.edit",
+ memoryId: "root-1",
+ expectedRevision: 1,
+ fact: "The user prefers concise replies.",
+ },
+ });
+ const arbitrary = yield* decode({
+ threadId: "thread-1",
+ mutation: { operation: "database.execute", sql: "DELETE FROM memory" },
+ }).pipe(Effect.exit);
+ const deleteWithoutRevision = yield* decode({
+ threadId: "thread-1",
+ mutation: { operation: "fact.delete", memoryId: "root-1" },
+ }).pipe(Effect.exit);
+
+ assert.equal(edit.mutation.operation, "fact.edit");
+ assert.isTrue(arbitrary._tag === "Failure");
+ assert.isTrue(deleteWithoutRevision._tag === "Failure");
+ }),
+ );
+});
diff --git a/packages/contracts/src/akeruMemory.ts b/packages/contracts/src/akeruMemory.ts
new file mode 100644
index 000000000..d1f6934bc
--- /dev/null
+++ b/packages/contracts/src/akeruMemory.ts
@@ -0,0 +1,411 @@
+import * as Schema from "effect/Schema";
+import * as Effect from "effect/Effect";
+
+import {
+ BotId,
+ GroupId,
+ IsoDateTime,
+ MessageId,
+ NonNegativeInt,
+ PositiveInt,
+ ProjectId,
+ ThreadId,
+ TrimmedNonEmptyString,
+} from "./baseSchemas.ts";
+
+export const AKERU_MEMORY_PACKET_MAX_FACTS = 24;
+export const AKERU_MEMORY_PACKET_MAX_CHARS = 12_000;
+export const AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS = 3_000;
+
+export const AkeruMemoryId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryId"));
+export type AkeruMemoryId = typeof AkeruMemoryId.Type;
+
+export const AkeruMemoryRootId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryRootId"));
+export type AkeruMemoryRootId = typeof AkeruMemoryRootId.Type;
+
+export const AkeruMemoryCandidateId = TrimmedNonEmptyString.pipe(
+ Schema.brand("AkeruMemoryCandidateId"),
+);
+export type AkeruMemoryCandidateId = typeof AkeruMemoryCandidateId.Type;
+
+export const AkeruMemoryTenantId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryTenantId"));
+export type AkeruMemoryTenantId = typeof AkeruMemoryTenantId.Type;
+
+export const AkeruMemoryUserId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryUserId"));
+export type AkeruMemoryUserId = typeof AkeruMemoryUserId.Type;
+
+export const AkeruMemoryEntityId = TrimmedNonEmptyString.pipe(Schema.brand("AkeruMemoryEntityId"));
+export type AkeruMemoryEntityId = typeof AkeruMemoryEntityId.Type;
+
+export const AkeruMemoryPartitionId = TrimmedNonEmptyString.pipe(
+ Schema.brand("AkeruMemoryPartitionId"),
+);
+export type AkeruMemoryPartitionId = typeof AkeruMemoryPartitionId.Type;
+
+export const AkeruMemoryScope = Schema.Literals([
+ "user",
+ "bot-user",
+ "bot",
+ "project",
+ "group",
+ "workspace",
+ "thread",
+]);
+export type AkeruMemoryScope = typeof AkeruMemoryScope.Type;
+
+export const AkeruMemoryVisibility = Schema.Literals(["private", "shared"]);
+export type AkeruMemoryVisibility = typeof AkeruMemoryVisibility.Type;
+
+export const AkeruMemoryApprovalState = Schema.Literals(["pending", "approved", "rejected"]);
+export type AkeruMemoryApprovalState = typeof AkeruMemoryApprovalState.Type;
+
+export const AkeruMemoryCandidateStatus = Schema.Literals(["pending", "approved", "rejected"]);
+export type AkeruMemoryCandidateStatus = typeof AkeruMemoryCandidateStatus.Type;
+
+export const AkeruMemoryTargetScope = Schema.Literals([
+ "private",
+ "bot",
+ "project",
+ "group",
+ "workspace",
+]);
+export type AkeruMemoryTargetScope = typeof AkeruMemoryTargetScope.Type;
+
+export const AkeruMemoryDeletionState = Schema.Literals(["active", "tombstoned", "deleted"]);
+export type AkeruMemoryDeletionState = typeof AkeruMemoryDeletionState.Type;
+
+export const AkeruMemoryKind = Schema.Literals([
+ "fact",
+ "preference",
+ "identity",
+ "relationship",
+ "routine",
+ "instruction",
+]);
+export type AkeruMemoryKind = typeof AkeruMemoryKind.Type;
+
+export const AkeruMemoryEntityKind = Schema.Literals([
+ "user",
+ "bot",
+ "person",
+ "project",
+ "group",
+ "workspace",
+ "other",
+]);
+export type AkeruMemoryEntityKind = typeof AkeruMemoryEntityKind.Type;
+
+export const AkeruMemoryConfidence = Schema.Number.check(
+ Schema.isBetween({ minimum: 0, maximum: 1 }),
+);
+export type AkeruMemoryConfidence = typeof AkeruMemoryConfidence.Type;
+
+export const AkeruMemoryPartition = Schema.Struct({
+ tenantId: AkeruMemoryTenantId,
+ scope: AkeruMemoryScope,
+ partitionId: AkeruMemoryPartitionId,
+});
+export type AkeruMemoryPartition = typeof AkeruMemoryPartition.Type;
+
+export const AkeruMemoryRevision = Schema.Struct({
+ id: AkeruMemoryId,
+ rootId: AkeruMemoryRootId,
+ revision: PositiveInt,
+ partition: AkeruMemoryPartition,
+ entityKind: AkeruMemoryEntityKind,
+ entityId: AkeruMemoryEntityId,
+ kind: AkeruMemoryKind,
+ value: Schema.Record(Schema.String, Schema.Unknown),
+ fact: TrimmedNonEmptyString,
+ sourceThreadId: Schema.NullOr(ThreadId),
+ sourceMessageId: Schema.NullOr(MessageId),
+ authorBotId: Schema.NullOr(BotId),
+ initiatingUserId: AkeruMemoryUserId,
+ createdAt: IsoDateTime,
+ confirmedAt: Schema.NullOr(IsoDateTime),
+ updatedAt: IsoDateTime,
+ confidence: AkeruMemoryConfidence,
+ approvalState: AkeruMemoryApprovalState,
+ supersedesId: Schema.NullOr(AkeruMemoryId),
+ supersededById: Schema.NullOr(AkeruMemoryId),
+ visibility: AkeruMemoryVisibility,
+ deletionState: AkeruMemoryDeletionState,
+ pinned: Schema.Boolean,
+ sensitive: Schema.Boolean,
+ affectedBotIds: Schema.Array(BotId),
+});
+export type AkeruMemoryRevision = typeof AkeruMemoryRevision.Type;
+
+export const AkeruMemoryCandidate = Schema.Struct({
+ candidateId: AkeruMemoryCandidateId,
+ tenantId: AkeruMemoryTenantId,
+ initiatingUserId: AkeruMemoryUserId,
+ sourceThreadId: ThreadId,
+ sourceMessageId: Schema.NullOr(MessageId),
+ authorBotId: Schema.NullOr(BotId),
+ fact: TrimmedNonEmptyString,
+ scope: AkeruMemoryTargetScope,
+ sensitive: Schema.Boolean,
+ confidence: AkeruMemoryConfidence,
+ affectedBotIds: Schema.Array(BotId),
+ status: AkeruMemoryCandidateStatus,
+ createdAt: IsoDateTime,
+ decidedAt: Schema.NullOr(IsoDateTime),
+ decidedMemoryRootId: Schema.NullOr(AkeruMemoryRootId),
+});
+export type AkeruMemoryCandidate = typeof AkeruMemoryCandidate.Type;
+
+export const AkeruMemoryCandidateDecision = Schema.Union([
+ Schema.Struct({
+ candidateId: AkeruMemoryCandidateId,
+ decision: Schema.Literal("approve"),
+ fact: Schema.optional(TrimmedNonEmptyString),
+ scope: Schema.optional(AkeruMemoryTargetScope),
+ }),
+ Schema.Struct({
+ candidateId: AkeruMemoryCandidateId,
+ decision: Schema.Literal("reject"),
+ }),
+]);
+export type AkeruMemoryCandidateDecision = typeof AkeruMemoryCandidateDecision.Type;
+
+export const AkeruMemoryDecisionReceipt = Schema.Struct({
+ candidateId: AkeruMemoryCandidateId,
+ status: Schema.Literals(["approved", "rejected"]),
+ fact: TrimmedNonEmptyString,
+ scope: AkeruMemoryTargetScope,
+ affectedBotIds: Schema.Array(BotId),
+ memoryRootId: Schema.NullOr(AkeruMemoryRootId),
+ createdAt: IsoDateTime,
+});
+export type AkeruMemoryDecisionReceipt = typeof AkeruMemoryDecisionReceipt.Type;
+
+export const AkeruMemoryArchiveFile = Schema.Struct({
+ path: TrimmedNonEmptyString,
+ mediaType: Schema.Literal("text/markdown"),
+ sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+ content: Schema.String,
+});
+export type AkeruMemoryArchiveFile = typeof AkeruMemoryArchiveFile.Type;
+
+export const AkeruMemoryArchiveV1 = Schema.Struct({
+ schemaVersion: Schema.Literal(1),
+ threadId: ThreadId,
+ complete: Schema.Boolean,
+ createdAt: IsoDateTime,
+ files: Schema.Array(AkeruMemoryArchiveFile),
+ manifestSha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+});
+export type AkeruMemoryArchiveV1 = typeof AkeruMemoryArchiveV1.Type;
+
+export const AkeruMemoryArchiveTarget = Schema.Literals(["thread", "bot", "project", "all"]);
+export type AkeruMemoryArchiveTarget = typeof AkeruMemoryArchiveTarget.Type;
+
+export const AkeruMemoryArchiveRevision = Schema.Struct({
+ revision: AkeruMemoryRevision,
+ sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+});
+export type AkeruMemoryArchiveRevision = typeof AkeruMemoryArchiveRevision.Type;
+
+export const AkeruMemoryInspectInput = Schema.Struct({ threadId: ThreadId });
+export type AkeruMemoryInspectInput = typeof AkeruMemoryInspectInput.Type;
+
+export const AkeruConversationMemoryRecord = Schema.Struct({
+ id: TrimmedNonEmptyString,
+ generationCount: NonNegativeInt,
+ originType: Schema.Literals(["initial", "reflection"]),
+ activeObservations: Schema.String,
+ bufferedObservations: Schema.String,
+ bufferedReflection: Schema.NullOr(Schema.String),
+ totalTokensObserved: NonNegativeInt,
+ observationTokenCount: NonNegativeInt,
+ createdAt: IsoDateTime,
+ updatedAt: IsoDateTime,
+});
+export type AkeruConversationMemoryRecord = typeof AkeruConversationMemoryRecord.Type;
+
+export const AkeruConversationMemorySnapshot = Schema.Struct({
+ current: Schema.NullOr(AkeruConversationMemoryRecord),
+ history: Schema.Array(AkeruConversationMemoryRecord),
+});
+export type AkeruConversationMemorySnapshot = typeof AkeruConversationMemorySnapshot.Type;
+
+export const AkeruMemoryArchiveConversation = Schema.Struct({
+ threadId: ThreadId,
+ snapshot: AkeruConversationMemorySnapshot,
+ sha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+});
+export type AkeruMemoryArchiveConversation = typeof AkeruMemoryArchiveConversation.Type;
+
+export const AkeruMemoryArchiveV2 = Schema.Struct({
+ schemaVersion: Schema.Literal(2),
+ anchorThreadId: ThreadId,
+ target: AkeruMemoryArchiveTarget,
+ complete: Schema.Boolean,
+ createdAt: IsoDateTime,
+ files: Schema.Array(AkeruMemoryArchiveFile),
+ revisions: Schema.Array(AkeruMemoryArchiveRevision),
+ conversations: Schema.Array(AkeruMemoryArchiveConversation),
+ manifestSha256: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+});
+export type AkeruMemoryArchiveV2 = typeof AkeruMemoryArchiveV2.Type;
+
+export const AkeruMemoryArchive = Schema.Union([AkeruMemoryArchiveV1, AkeruMemoryArchiveV2]);
+export type AkeruMemoryArchive = typeof AkeruMemoryArchive.Type;
+
+export const AkeruMemorySnapshot = Schema.Struct({
+ threadId: ThreadId,
+ durable: Schema.Array(AkeruMemoryRevision),
+ histories: Schema.Array(
+ Schema.Struct({
+ rootId: AkeruMemoryRootId,
+ revisions: Schema.Array(AkeruMemoryRevision),
+ }),
+ ),
+ pending: Schema.Array(AkeruMemoryCandidate),
+ conversation: AkeruConversationMemorySnapshot,
+});
+export type AkeruMemorySnapshot = typeof AkeruMemorySnapshot.Type;
+
+export const AkeruMemoryExportInput = Schema.Struct({
+ threadId: ThreadId,
+ complete: Schema.Boolean,
+ target: AkeruMemoryArchiveTarget.pipe(
+ Schema.withDecodingDefault(Effect.succeed("thread" as const)),
+ ),
+});
+export type AkeruMemoryExportInput = typeof AkeruMemoryExportInput.Type;
+
+export const AkeruMemoryImportClassification = Schema.Literals([
+ "new",
+ "changed",
+ "conflicting",
+ "skipped",
+]);
+export type AkeruMemoryImportClassification = typeof AkeruMemoryImportClassification.Type;
+
+export const AkeruMemoryImportPreviewItem = Schema.Struct({
+ rootId: AkeruMemoryRootId,
+ classification: AkeruMemoryImportClassification,
+ reason: TrimmedNonEmptyString,
+});
+export type AkeruMemoryImportPreviewItem = typeof AkeruMemoryImportPreviewItem.Type;
+
+export const AkeruMemoryImportPreviewInput = Schema.Struct({
+ threadId: ThreadId,
+ target: AkeruMemoryArchiveTarget,
+ archive: AkeruMemoryArchiveV2,
+});
+export type AkeruMemoryImportPreviewInput = typeof AkeruMemoryImportPreviewInput.Type;
+
+export const AkeruMemoryImportPreview = Schema.Struct({
+ previewHash: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+ items: Schema.Array(AkeruMemoryImportPreviewItem),
+});
+export type AkeruMemoryImportPreview = typeof AkeruMemoryImportPreview.Type;
+
+export const AkeruMemoryImportApplyInput = Schema.Struct({
+ ...AkeruMemoryImportPreviewInput.fields,
+ previewHash: Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/)),
+});
+export type AkeruMemoryImportApplyInput = typeof AkeruMemoryImportApplyInput.Type;
+
+export const AkeruMemoryImportApplyResult = Schema.Struct({
+ imported: NonNegativeInt,
+ changed: NonNegativeInt,
+ skipped: NonNegativeInt,
+});
+export type AkeruMemoryImportApplyResult = typeof AkeruMemoryImportApplyResult.Type;
+
+export const AkeruMemoryMutation = Schema.Union([
+ Schema.Struct({
+ operation: Schema.Literal("candidate.decide"),
+ decision: AkeruMemoryCandidateDecision,
+ }),
+ Schema.Struct({
+ operation: Schema.Literal("fact.edit"),
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ fact: TrimmedNonEmptyString,
+ }),
+ Schema.Struct({
+ operation: Schema.Literal("fact.pin"),
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ pinned: Schema.Boolean,
+ }),
+ Schema.Struct({
+ operation: Schema.Literal("fact.scope"),
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ scope: AkeruMemoryTargetScope,
+ }),
+ Schema.Struct({
+ operation: Schema.Literal("fact.forget"),
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ }),
+ Schema.Struct({
+ operation: Schema.Literal("fact.delete"),
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ }),
+ Schema.Struct({ operation: Schema.Literal("conversation.clear") }),
+]);
+export type AkeruMemoryMutation = typeof AkeruMemoryMutation.Type;
+
+export const AkeruMemoryMutateInput = Schema.Struct({
+ threadId: ThreadId,
+ mutation: AkeruMemoryMutation,
+});
+export type AkeruMemoryMutateInput = typeof AkeruMemoryMutateInput.Type;
+
+export const AkeruMemoryMutationResult = Schema.Union([
+ Schema.Struct({ kind: Schema.Literal("candidate"), receipt: AkeruMemoryDecisionReceipt }),
+ Schema.Struct({ kind: Schema.Literal("revision"), revision: AkeruMemoryRevision }),
+ Schema.Struct({ kind: Schema.Literal("deleted"), memoryId: AkeruMemoryRootId }),
+ Schema.Struct({ kind: Schema.Literal("conversation-cleared") }),
+]);
+export type AkeruMemoryMutationResult = typeof AkeruMemoryMutationResult.Type;
+
+export class AkeruMemoryOperationError extends Schema.TaggedErrorClass<AkeruMemoryOperationError>()(
+ "AkeruMemoryOperationError",
+ { operation: TrimmedNonEmptyString, detail: TrimmedNonEmptyString },
+) {}
+
+export const AkeruMemoryPacketFact = Schema.Struct({
+ memoryId: AkeruMemoryRootId,
+ expectedRevision: PositiveInt,
+ scope: AkeruMemoryScope,
+ kind: AkeruMemoryKind,
+ fact: TrimmedNonEmptyString,
+ pinned: Schema.Boolean,
+ confidence: AkeruMemoryConfidence,
+ updatedAt: IsoDateTime,
+});
+export type AkeruMemoryPacketFact = typeof AkeruMemoryPacketFact.Type;
+
+export const AkeruMemoryPacket = Schema.Struct({
+ threadId: ThreadId,
+ facts: Schema.Array(AkeruMemoryPacketFact).check(
+ Schema.isMaxLength(AKERU_MEMORY_PACKET_MAX_FACTS),
+ ),
+ estimatedTokens: NonNegativeInt.check(
+ Schema.isLessThanOrEqualTo(AKERU_MEMORY_PACKET_MAX_ESTIMATED_TOKENS),
+ ),
+ rendered: Schema.String.check(Schema.isMaxLength(AKERU_MEMORY_PACKET_MAX_CHARS)),
+});
+export type AkeruMemoryPacket = typeof AkeruMemoryPacket.Type;
+
+export const AkeruMemoryThreadAccess = Schema.Struct({
+ tenantId: AkeruMemoryTenantId,
+ userId: AkeruMemoryUserId,
+ threadId: ThreadId,
+ projectId: ProjectId,
+ workspaceRoot: TrimmedNonEmptyString,
+ botId: Schema.NullOr(BotId),
+ groupId: Schema.NullOr(GroupId),
+ respondingBotId: Schema.NullOr(BotId),
+ groupMemberBotIds: Schema.Array(BotId),
+});
+export type AkeruMemoryThreadAccess = typeof AkeruMemoryThreadAccess.Type;
diff --git a/packages/contracts/src/akeruUsage.test.ts b/packages/contracts/src/akeruUsage.test.ts
new file mode 100644
index 000000000..d9985840c
--- /dev/null
+++ b/packages/contracts/src/akeruUsage.test.ts
@@ -0,0 +1,28 @@
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+
+import { AkeruBotUsageSnapshot } from "./akeruUsage.ts";
+
+it.effect("decodes bot usage with unavailable provider totals", () =>
+ Effect.gen(function* () {
+ const snapshot = yield* Schema.decodeUnknownEffect(AkeruBotUsageSnapshot)({
+ botId: "bot-1",
+ consumedTokens: 12,
+ reservedTokens: 32,
+ measurements: {
+ input: { tokens: 5, unavailableEntries: 0 },
+ output: { tokens: 7, unavailableEntries: 0 },
+ observer: { tokens: 0, unavailableEntries: 1 },
+ reflector: { tokens: 0, unavailableEntries: 1 },
+ },
+ entries: [],
+ usageCap: { unit: "tokens", limit: 1_000 },
+ estimatedCost: { status: "unavailable", usd: null },
+ subscriptionPool: { status: "unavailable", used: null, limit: null, unit: null },
+ });
+
+ assert.strictEqual(snapshot.usageCap?.limit, 1_000);
+ assert.strictEqual(snapshot.estimatedCost.status, "unavailable");
+ }),
+);
diff --git a/packages/contracts/src/akeruUsage.ts b/packages/contracts/src/akeruUsage.ts
new file mode 100644
index 000000000..7f613bd2f
--- /dev/null
+++ b/packages/contracts/src/akeruUsage.ts
@@ -0,0 +1,101 @@
+import * as Schema from "effect/Schema";
+
+import {
+ BotId,
+ IsoDateTime,
+ NonNegativeInt,
+ ThreadId,
+ TrimmedNonEmptyString,
+ TurnId,
+} from "./baseSchemas.ts";
+import { ProviderDriverKind } from "./providerInstance.ts";
+import { BotUsageCap } from "./orchestration.ts";
+
+export const AkeruUsageReservationId = TrimmedNonEmptyString.pipe(
+ Schema.brand("AkeruUsageReservationId"),
+);
+export type AkeruUsageReservationId = typeof AkeruUsageReservationId.Type;
+
+export const AkeruUsageCategory = Schema.Literals([
+ "turn",
+ "tool",
+ "observer",
+ "reflector",
+ "extraction",
+ "recall",
+ "routine",
+ "delegated",
+]);
+export type AkeruUsageCategory = typeof AkeruUsageCategory.Type;
+
+export const AkeruUsageState = Schema.Literals(["reserved", "reported", "unavailable", "released"]);
+export type AkeruUsageState = typeof AkeruUsageState.Type;
+
+export const AkeruUsageEntry = Schema.Struct({
+ reservationId: AkeruUsageReservationId,
+ sourceKey: TrimmedNonEmptyString,
+ botId: BotId,
+ threadId: Schema.NullOr(ThreadId),
+ turnId: Schema.NullOr(TurnId),
+ category: AkeruUsageCategory,
+ state: AkeruUsageState,
+ reservedTokens: NonNegativeInt,
+ inputTokens: Schema.NullOr(NonNegativeInt),
+ outputTokens: Schema.NullOr(NonNegativeInt),
+ reasoningTokens: Schema.NullOr(NonNegativeInt),
+ provider: Schema.NullOr(ProviderDriverKind),
+ model: Schema.NullOr(TrimmedNonEmptyString),
+ unavailableReason: Schema.NullOr(TrimmedNonEmptyString),
+ createdAt: IsoDateTime,
+ settledAt: Schema.NullOr(IsoDateTime),
+});
+export type AkeruUsageEntry = typeof AkeruUsageEntry.Type;
+
+export const AkeruBotUsageSummary = Schema.Struct({
+ botId: BotId,
+ consumedTokens: NonNegativeInt,
+ reservedTokens: NonNegativeInt,
+ measurements: Schema.Struct({
+ input: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),
+ output: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),
+ observer: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),
+ reflector: Schema.Struct({ tokens: NonNegativeInt, unavailableEntries: NonNegativeInt }),
+ }),
+ entries: Schema.Array(AkeruUsageEntry),
+});
+export type AkeruBotUsageSummary = typeof AkeruBotUsageSummary.Type;
+
+export const AkeruBotUsageInput = Schema.Struct({ botId: BotId });
+export type AkeruBotUsageInput = typeof AkeruBotUsageInput.Type;
+
+export const AkeruBotUsageSnapshot = Schema.Struct({
+ ...AkeruBotUsageSummary.fields,
+ usageCap: Schema.NullOr(BotUsageCap),
+ estimatedCost: Schema.Union([
+ Schema.Struct({
+ status: Schema.Literal("available"),
+ usd: Schema.Number.check(Schema.isFinite(), Schema.isGreaterThanOrEqualTo(0)),
+ }),
+ Schema.Struct({ status: Schema.Literal("unavailable"), usd: Schema.Null }),
+ ]),
+ subscriptionPool: Schema.Union([
+ Schema.Struct({
+ status: Schema.Literal("available"),
+ used: NonNegativeInt,
+ limit: NonNegativeInt,
+ unit: TrimmedNonEmptyString,
+ }),
+ Schema.Struct({
+ status: Schema.Literal("unavailable"),
+ used: Schema.Null,
+ limit: Schema.Null,
+ unit: Schema.Null,
+ }),
+ ]),
+});
+export type AkeruBotUsageSnapshot = typeof AkeruBotUsageSnapshot.Type;
+
+export class AkeruBotUsageReadError extends Schema.TaggedErrorClass<AkeruBotUsageReadError>()(
+ "AkeruBotUsageReadError",
+ { botId: BotId, detail: TrimmedNonEmptyString },
+) {}
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 759b87fdf..bd9e7305d 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,6 +1,8 @@
export * from "./baseSchemas.ts";
export * from "./background.ts";
export * from "./productFeedback.ts";
+export * from "./akeruMemory.ts";
+export * from "./akeruUsage.ts";
export * from "./auth.ts";
export * from "./environment.ts";
export * from "./environmentHttp.ts";