status_code: number;

headers?: Record<string, string>;

body: unknown;

if (raw === undefined || raw === null || raw === "") return undefined;

const n = typeof raw === "number" ? raw : parseInt(String(raw), 10);

return Number.isFinite(n) ? n : undefined;

req: ApiRequest,

secret: string | undefined,

): Response | null {

if (!secret) return null;

const auth = req.headers?.["authorization"] || req.headers?.["Authorization"];

if (

typeof auth !== "string" ||

!timingSafeCompare(auth, `Bearer ${secret}`)

) {

return { status_code: 401, body: { error: "unauthorized" } };

}

return null;

secret: string | undefined,

feature: string,

): Response | null {

if (secret) return null;

return {

status_code: 503,

body: { error: `${feature} requires AGENTMEMORY_SECRET` },

};

error: string;

flag: string;

enableHow: string;

docsHref: string;

}): Response {

return {

status_code: 503,

body: opts,

};

return flagDisabledResponse({

error: "Knowledge graph not enabled",

flag: "GRAPH_EXTRACTION_ENABLED",

enableHow: "Set GRAPH_EXTRACTION_ENABLED=true and restart. Requires an LLM provider key.",

docsHref: "https://github.com/rohitg00/agentmemory#knowledge-graph",

});

return flagDisabledResponse({

error: "Consolidation pipeline not enabled",

flag: "CONSOLIDATION_ENABLED",

enableHow: "Set CONSOLIDATION_ENABLED=true and restart. Requires an LLM provider key.",

docsHref: "https://github.com/rohitg00/agentmemory#consolidation",

});

return flagDisabledResponse({

error: "Memory slots not enabled",

flag: "AGENTMEMORY_SLOTS",

enableHow: "Set AGENTMEMORY_SLOTS=true (in ~/.agentmemory/.env or the shell) and restart.",

docsHref: "https://github.com/rohitg00/agentmemory#memory-slots",

});

return flagDisabledResponse({

error: "Slot reflection not enabled",

flag: "AGENTMEMORY_REFLECT",

enableHow: "Set AGENTMEMORY_REFLECT=true (in ~/.agentmemory/.env or the shell) and restart. Requires AGENTMEMORY_SLOTS=true.",

docsHref: "https://github.com/rohitg00/agentmemory#memory-slots",

});

if (typeof value !== "string") return null;

const trimmed = value.trim();

return trimmed ? trimmed : null;

if (value === undefined || value === null) return undefined;

if (typeof value === "number") return Number.isFinite(value) ? value : null;

if (typeof value === "string") {

const trimmed = value.trim();

if (!trimmed) return undefined;

const parsed = Number(trimmed);

return Number.isFinite(parsed) ? parsed : null;

}

return null;

const parsed = parseOptionalFiniteNumber(value);

if (parsed === undefined || parsed === null) return parsed;

if (!Number.isInteger(parsed) || parsed < 1) return null;

return parsed;

sdk: ISdk,

kv: StateKV,

secret?: string,

metricsStore?: MetricsStore,

provider?: ResilientProvider | { circuitState?: unknown },

): void {

sdk.registerFunction(

"middleware::api-auth",

async (input: {

request?: { headers?: Record<string, string | undefined> };

}) => {

if (!secret) return { action: "continue" };

const headers = input?.request?.headers || {};

const auth = headers["authorization"] || headers["Authorization"];

if (

typeof auth !== "string" ||

!timingSafeCompare(auth, `Bearer ${secret}`)

) {

return {

action: "respond",

response: { status_code: 401, body: { error: "unauthorized" } },

};

}

return { action: "continue" };

},

);

sdk.registerFunction("api::liveness",

async (): Promise<Response> => ({

status_code: 200,

body: { status: "ok", service: "agentmemory", viewerPort: getBoundViewerPort(), viewerSkipped: getViewerSkipped() },

}),

);

sdk.registerTrigger({

type: "http",

function_id: "api::liveness",

config: { api_path: "/agentmemory/livez", http_method: "GET" },

});

sdk.registerFunction("api::config-flags",

async (req: ApiRequest): Promise<Response> => {

const authErr = checkAuth(req, secret);

if (authErr) return authErr;

const providerKind = detectLlmProviderKind();

const embeddingProvider = detectEmbeddingProvider() ? "embeddings" : "none";

const flags = [

{

key: "GRAPH_EXTRACTION_ENABLED",

label: "Knowledge graph extraction",

enabled: isGraphExtractionEnabled(),

default: false,

affects: ["Graph", "Dashboard"],

needsLlm: true,

description: "Extracts entities and relations from observations into a knowledge graph.",

enableHow: "Set GRAPH_EXTRACTION_ENABLED=true and provide an LLM key, then restart.",

docsHref: "https://github.com/rohitg00/agentmemory#knowledge-graph",

},

{

key: "CONSOLIDATION_ENABLED",

label: "Memory consolidation",

enabled: isConsolidationEnabled(),

default: false,

affects: ["Dashboard", "Memories", "Crystals"],

needsLlm: true,

description: "Periodically summarizes sessions into semantic facts + procedures.",

enableHow: "Set CONSOLIDATION_ENABLED=true and provide an LLM key, then restart.",

docsHref: "https://github.com/rohitg00/agentmemory#consolidation",

},

{

key: "AGENTMEMORY_AUTO_COMPRESS",

label: "LLM-powered observation compression",

enabled: isAutoCompressEnabled(),

default: false,

affects: ["Memories", "Timeline"],

needsLlm: true,

description: "Every observation is compressed by the LLM for richer summaries (costs tokens). OFF uses zero-LLM synthetic compression.",

enableHow: "Set AGENTMEMORY_AUTO_COMPRESS=true and provide an LLM key.",

docsHref: "https://github.com/rohitg00/agentmemory/issues/138",

},

{

key: "AGENTMEMORY_INJECT_CONTEXT",

label: "In-conversation context injection",

enabled: isContextInjectionEnabled(),

default: false,

affects: ["Hooks"],

needsLlm: false,

description: "Hooks write recalled context into Claude Code's conversation. OFF captures in the background without injecting.",

enableHow: "Set AGENTMEMORY_INJECT_CONTEXT=true and restart.",

docsHref: "https://github.com/rohitg00/agentmemory/issues/143",

},

];

return {

status_code: 200,

body: {

version: VERSION,

provider: providerKind,

embeddingProvider,

flags,

},

};

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::config-flags",

config: {

api_path: "/agentmemory/config/flags",

http_method: "GET",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::health",

async (req: ApiRequest): Promise<Response> => {

const health = await getLatestHealth(kv);

const functionMetrics = metricsStore ? await metricsStore.getAll() : [];

const circuitBreaker =

provider && "circuitState" in provider ? provider.circuitState : null;

const status = health?.status || "healthy";

const statusCode = status === "critical" ? 503 : 200;

return {

status_code: statusCode,

body: {

status,

service: "agentmemory",

version: VERSION,

health: health || null,

functionMetrics,

circuitBreaker,

viewerPort: getBoundViewerPort(),

viewerSkipped: getViewerSkipped(),

},

};

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::health",

config: {

api_path: "/agentmemory/health",

http_method: "GET",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::observe",

async (req: ApiRequest<HookPayload>): Promise<Response> => {

const body = (req.body ?? {}) as Record<string, unknown>;

const hookType = asNonEmptyString(body.hookType);

const sessionId = asNonEmptyString(body.sessionId);

const project = asNonEmptyString(body.project);

const cwd = asNonEmptyString(body.cwd);

const timestamp = asNonEmptyString(body.timestamp);

if (!hookType || !sessionId || !project || !cwd || !timestamp) {

return {

status_code: 400,

body: {

error:

"hookType, sessionId, project, cwd, and timestamp are required strings",

},

};

}

const payload: HookPayload = {

hookType: hookType as HookPayload["hookType"],

sessionId,

project,

cwd,

timestamp,

data: body.data,

};

const result = await sdk.trigger({ function_id: "mem::observe", payload });

return { status_code: 201, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::observe",

config: {

api_path: "/agentmemory/observe",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::context",

async (

req: ApiRequest<{

sessionId: string;

project: string;

budget?: number;

agentId?: string;

}>,

): Promise<Response> => {

const body = (req.body ?? {}) as Record<string, unknown>;

const sessionId = asNonEmptyString(body.sessionId);

const project = asNonEmptyString(body.project);

if (!sessionId || !project) {

return {

status_code: 400,

body: { error: "sessionId and project are required strings" },

};

}

const budget = parseOptionalPositiveInt(body.budget);

if (budget === null) {

return {

status_code: 400,

body: { error: "budget must be a positive integer" },

};

}

// Propagate agentId so mem::context applies the same cross-agent

// isolation filter as mem::search. Honors body.agentId, ?agentId=,

// or the worker's AGENT_ID fallback under AGENTMEMORY_AGENT_SCOPE=isolated.

const queryAgentId =

typeof (req as { query_params?: Record<string, string> })

.query_params?.["agentId"] === "string"

? (req as { query_params: Record<string, string> })

.query_params["agentId"]

: undefined;

const bodyAgentId =

typeof body.agentId === "string" && body.agentId.trim().length > 0

? (body.agentId as string).trim()

: undefined;

const payload: {

sessionId: string;

project: string;

budget?: number;

agentId?: string;

} = {

sessionId,

project,

};

if (budget !== undefined) payload.budget = budget;

const agentId = bodyAgentId ?? queryAgentId;

if (agentId !== undefined) payload.agentId = agentId;

const result = await sdk.trigger({ function_id: "mem::context", payload });

return { status_code: 200, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::context",

config: {

api_path: "/agentmemory/context",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::search",

async (

req: ApiRequest<{

query: string;

limit?: number;

project?: string;

cwd?: string;

format?: string;

token_budget?: number;

agentId?: string;

}>,

): Promise<Response> => {

const body = (req.body ?? {}) as Record<string, unknown>;

const queryAgentId =

typeof (req as { query_params?: Record<string, string> })

.query_params?.["agentId"] === "string"

? (req as { query_params: Record<string, string> })

.query_params["agentId"]

: undefined;

if (typeof body.query !== "string" || !body.query.trim()) {

return { status_code: 400, body: { error: "query is required and must be a non-empty string" } };

}

if (

body.limit !== undefined &&

(!Number.isInteger(body.limit) || (body.limit as number) < 1)

) {

return { status_code: 400, body: { error: "limit must be a positive integer" } };

}

if (body.project !== undefined && typeof body.project !== "string") {

return { status_code: 400, body: { error: "project must be a string" } };

}

if (body.cwd !== undefined && typeof body.cwd !== "string") {

return { status_code: 400, body: { error: "cwd must be a string" } };

}

if (

body.format !== undefined &&

(typeof body.format !== "string" ||

!["full", "compact", "narrative"].includes(body.format.trim().toLowerCase()))

) {

return {

status_code: 400,

body: { error: "format must be one of: full, compact, narrative" },

};

}

if (

body.token_budget !== undefined &&

(!Number.isInteger(body.token_budget) || (body.token_budget as number) < 1)

) {

return {

status_code: 400,

body: { error: "token_budget must be a positive integer" },

};

}

// #817: propagate agentId so the upstream isolation filter

// applies. Honors body.agentId (POST body), ?agentId=... query

// param, or implicit fallback to the worker's AGENT_ID when

// AGENTMEMORY_AGENT_SCOPE=isolated.

const bodyAgentId =

typeof body.agentId === "string" && body.agentId.trim().length > 0

? (body.agentId as string).trim()

: undefined;

const payload = {

query: body.query.trim(),

limit: body.limit as number | undefined,

project: body.project as string | undefined,

cwd: body.cwd as string | undefined,

format:

typeof body.format === "string"

? body.format.trim().toLowerCase()

: undefined,

token_budget: body.token_budget as number | undefined,

agentId: bodyAgentId ?? queryAgentId,

};

const result = await sdk.trigger({ function_id: "mem::search", payload: payload });

return { status_code: 200, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::search",

config: {

api_path: "/agentmemory/search",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::compress-file",

async (req: ApiRequest<{ filePath: string }>): Promise<Response> => {

const authErr = checkAuth(req, secret);

if (authErr) return authErr;

const body = (req.body ?? {}) as Record<string, unknown>;

const filePath = asNonEmptyString(body.filePath);

if (!filePath) {

return {

status_code: 400,

body: { error: "filePath is required and must be a non-empty string" },

};

}

const result = await sdk.trigger({

function_id: "mem::compress-file",

payload: { filePath },

});

return { status_code: 200, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::compress-file",

config: { api_path: "/agentmemory/compress-file", http_method: "POST" },

});

sdk.registerFunction("api::replay::load",

async (req: ApiRequest): Promise<Response> => {

const authErr = checkAuth(req, secret);

if (authErr) return authErr;

const sessionId = asNonEmptyString(req.query_params?.["sessionId"]);

if (!sessionId) {

return { status_code: 400, body: { error: "sessionId is required" } };

}

const result = await sdk.trigger({

function_id: "mem::replay::load",

payload: { sessionId },

});

return { status_code: 200, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::replay::load",

config: { api_path: "/agentmemory/replay/load", http_method: "GET" },

});

sdk.registerFunction("api::replay::sessions",

async (req: ApiRequest): Promise<Response> => {

const authErr = checkAuth(req, secret);

if (authErr) return authErr;

const sessions = await kv.list<Session>(KV.sessions);

sessions.sort((a, b) =>

(b.startedAt || "").localeCompare(a.startedAt || ""),

);

return { status_code: 200, body: { success: true, sessions } };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::replay::sessions",

config: { api_path: "/agentmemory/replay/sessions", http_method: "GET" },

});

sdk.registerFunction("api::replay::import",

async (

req: ApiRequest<{ path?: string; maxFiles?: number }>,

): Promise<Response> => {

const authErr = checkAuth(req, secret);

if (authErr) return authErr;

const body = (req.body ?? {}) as Record<string, unknown>;

const payload: { path?: string; maxFiles?: number } = {};

if (body.path !== undefined) {

if (typeof body.path !== "string" || body.path.trim().length === 0) {

return {

status_code: 400,

body: { error: "path must be a non-empty string" },

};

}

payload.path = body.path.trim();

}

if (body.maxFiles !== undefined) {

const n = body.maxFiles as number;

if (

!Number.isInteger(n) ||

n < 1 ||

n > MAX_FILES_UPPER_BOUND

) {

return {

status_code: 400,

body: {

error: `maxFiles must be an integer between 1 and ${MAX_FILES_UPPER_BOUND}`,

},

};

}

payload.maxFiles = n;

}

const result = await sdk.trigger({

function_id: "mem::replay::import-jsonl",

payload,

});

return { status_code: 202, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::replay::import",

config: { api_path: "/agentmemory/replay/import-jsonl", http_method: "POST" },

});

sdk.registerFunction("api::session::start",

async (

req: ApiRequest<{ sessionId: string; project: string; cwd: string }>,

): Promise<Response> => {

const body = (req.body ?? {}) as Record<string, unknown>;

const sessionId = asNonEmptyString(body.sessionId);

const project = asNonEmptyString(body.project);

const cwd = asNonEmptyString(body.cwd);

if (!sessionId || !project || !cwd) {

return {

status_code: 400,

body: {

error: "sessionId, project, and cwd are required non-empty strings",

},

};

}

const title = typeof body.title === "string" ? body.title.trim() : undefined;

// allow session/start to override AGENT_ID from request body

// (multi-agent runtimes that route many roles through one server

// process). Falls back to the AGENT_ID env on the server.

const requestAgentId =

typeof body.agentId === "string" && body.agentId.trim().length > 0

? body.agentId.trim().slice(0, 128)

: undefined;

const agentId = requestAgentId ?? getAgentId();

const session: Session = {

id: sessionId,

project,

cwd,

startedAt: new Date().toISOString(),

status: "active",

observationCount: 0,

...(title ? { summary: title.slice(0, 200) } : {}),

...(title ? { firstPrompt: title.slice(0, 200) } : {}),

...(agentId ? { agentId } : {}),

};

await kv.set(KV.sessions, sessionId, session);

const contextResult = await sdk.trigger<

{ sessionId: string; project: string; agentId?: string },

{ context: string }

>({

function_id: "mem::context",

payload: { sessionId, project, ...(agentId ? { agentId } : {}) },

});

return {

status_code: 200,

body: { session, context: contextResult.context },

};

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::session::start",

config: {

api_path: "/agentmemory/session/start",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::session::end",

async (req: ApiRequest<{ sessionId: string }>): Promise<Response> => {

const sessionId = asNonEmptyString((req.body as Record<string, unknown>)?.sessionId);

if (!sessionId) {

return {

status_code: 400,

body: { error: "sessionId is required and must be a non-empty string" },

};

}

await kv.update(KV.sessions, sessionId, [

{ type: "set", path: "endedAt", value: new Date().toISOString() },

{ type: "set", path: "status", value: "completed" },

]);

// Fan out session-stopped lifecycle (non-blocking).

try {

sdk.trigger({

function_id: "event::session::stopped",

payload: { sessionId },

action: TriggerAction.Void(),

});

} catch (err) {

logger.warn("event::session::stopped trigger failed", {

sessionId,

error: err instanceof Error ? err.message : String(err),

});

}

return { status_code: 200, body: { success: true } };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::session::end",

config: {

api_path: "/agentmemory/session/end",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::summarize",

async (req: ApiRequest<{ sessionId: string }>): Promise<Response> => {

const sessionId = asNonEmptyString((req.body as Record<string, unknown>)?.sessionId);

if (!sessionId) {

return { status_code: 400, body: { error: "sessionId is required" } };

}

const result = await sdk.trigger({

function_id: "mem::summarize",

payload: { sessionId },

});

return { status_code: 200, body: result };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::summarize",

config: {

api_path: "/agentmemory/summarize",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::session::commit",

async (req: ApiRequest): Promise<Response> => {

const body = (req.body ?? {}) as Record<string, unknown>;

const sha = asNonEmptyString(body.sha);

if (!sha) {

return {

status_code: 400,

body: { error: "sha is required and must be a non-empty string" },

};

}

const sessionId = asNonEmptyString(body.sessionId) ?? undefined;

const branch = asNonEmptyString(body.branch) ?? undefined;

const repo = asNonEmptyString(body.repo) ?? undefined;

const message = asNonEmptyString(body.message) ?? undefined;

const author = asNonEmptyString(body.author) ?? undefined;

const authoredAt = asNonEmptyString(body.authoredAt) ?? undefined;

const files = Array.isArray(body.files)

? (body.files as unknown[]).filter(

(f): f is string => typeof f === "string" && f.length > 0,

)

: undefined;

const link = await withKeyedLock(`commit:${sha}`, async () => {

const existing = await kv.get<CommitLink>(KV.commits, sha);

const sessionSet = new Set<string>(existing?.sessionIds ?? []);

if (sessionId) sessionSet.add(sessionId);

const merged: CommitLink = {

sha,

shortSha: existing?.shortSha ?? sha.slice(0, 7),

branch: branch ?? existing?.branch,

repo: repo ?? existing?.repo,

message: message ?? existing?.message,

author: author ?? existing?.author,

authoredAt: authoredAt ?? existing?.authoredAt,

files: files ?? existing?.files,

sessionIds: Array.from(sessionSet),

linkedAt: existing?.linkedAt ?? new Date().toISOString(),

};

await kv.set(KV.commits, sha, merged);

return merged;

});

if (sessionId) {

await withKeyedLock(`session:${sessionId}`, async () => {

const session = await kv.get<Session>(KV.sessions, sessionId);

if (!session) return;

const shaSet = new Set<string>(session.commitShas ?? []);

shaSet.add(sha);

session.commitShas = Array.from(shaSet);

await kv.set(KV.sessions, sessionId, session);

});

}

return { status_code: 200, body: { commit: link } };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::session::commit",

config: {

api_path: "/agentmemory/session/commit",

http_method: "POST",

middleware_function_ids: ["middleware::api-auth"],

},

});

sdk.registerFunction("api::session::by-commit",

async (req: ApiRequest): Promise<Response> => {

const authErr = checkAuth(req, secret);

if (authErr) return authErr;

const sha = asNonEmptyString(req.query_params?.["sha"]);

if (!sha) {

return {

status_code: 400,

body: { error: "sha is required and must be a non-empty string" },

};

}

const link = await kv.get<CommitLink>(KV.commits, sha);

if (!link) {

return {

status_code: 404,

body: { error: "no sessions linked to this commit" },

};

}

const fetched = await Promise.all(

(link.sessionIds ?? []).map((sid) => kv.get<Session>(KV.sessions, sid)),

);

const sessions = fetched.filter((s): s is Session => s !== null);

return { status_code: 200, body: { commit: link, sessions } };

},

);

sdk.registerTrigger({

type: "http",

function_id: "api::session::by-commit",