@xemahq/opencode-xema-plugin 0.1.4 → 0.1.5

package/src/tools/xema-memory.ts

@@ -0,0 +1,232 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── xema_memory_set / xema_memory_get ──
+//
+// Thin session-memory tools wired into the shared memory-api. Inspired by
+// Claude Code's memory model: agents can set *named* facts that survive
+// compaction and be read back with a tag/kind filter.
+//
+// Scope: every write is project-scoped (orgId + projectId from context.json)
+// and tagged with the opencode session id so memories from different runs
+// do not bleed together on recall. Role-gated — only interactive / primary
+// pipeline roles may write; anyone may read.
+//
+// Transport: direct HTTP to `MEMORY_API_URL`. When the env var is absent,
+// the tool fails fast instead of silently dropping data — memory is either
+// on or off for a deployment, not best-effort. Authentication uses the
+// per-allocation Keycloak service JWT read fresh from the service-token
+// file workspace-proxy writes (see `service-token.ts`).
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { z } from 'zod';
+
+import { tool } from '../opencode-types.js';
+import { loadSessionStateForTool } from './runtime.js';
+import { serviceTokenAuthorizationHeader } from './service-token.js';
+import { toJsonString } from './shared.js';
+
+const MEMORY_KINDS = [
+  'GENERAL',
+  'DECISION',
+  'CONSTRAINT',
+  'PATTERN',
+  'LESSON',
+  'EPISODIC',
+  'PROCEDURAL',
+  'CORRECTION',
+] as const;
+
+type MemoryKind = (typeof MEMORY_KINDS)[number];
+
+const SET_ARGS = {
+  content: z
+    .string()
+    .min(5)
+    .describe(
+      'The memory statement. A short fact / preference / lesson phrased as ' +
+        'a complete sentence. Avoid ephemeral context ("just now the user said"); ' +
+        'memory persists across turns.',
+    ),
+  kind: z
+    .enum(MEMORY_KINDS)
+    .default('GENERAL')
+    .describe(
+      'Kind of memory. Use DECISION for choices made, CONSTRAINT for ' +
+        'hard limits, LESSON for insights from failures, PATTERN for ' +
+        'recurring structures, CORRECTION when overriding a prior memory, ' +
+        'GENERAL otherwise.',
+    ),
+  tag: z
+    .string()
+    .optional()
+    .describe(
+      'Optional short tag that appears in the originRef so the memory can ' +
+        'later be recalled by the same tag (e.g. "preferences", "style").',
+    ),
+  importance: z
+    .number()
+    .int()
+    .min(1)
+    .max(4)
+    .optional()
+    .describe('1=LOW, 2=NORMAL (default), 3=HIGH, 4=CRITICAL.'),
+};
+
+const GET_ARGS = {
+  kind: z
+    .enum(MEMORY_KINDS)
+    .optional()
+    .describe('Filter to a specific kind. Omit for all.'),
+  tag: z
+    .string()
+    .optional()
+    .describe(
+      'Filter to memories written with this tag. Matches on originRef suffix.',
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(50)
+    .default(20)
+    .describe('Maximum number of memories to return.'),
+};
+
+interface MemoryApiCtx {
+  baseUrl: string;
+  orgId: string;
+  projectId: string;
+  actorId: string;
+  sessionId: string;
+  role: string;
+}
+
+function resolveMemoryApiCtx(workspaceDir: string, toolName: string): MemoryApiCtx {
+  const state = loadSessionStateForTool(workspaceDir, toolName);
+  // ── Why an env var and not the KernelState/etcd service registry ──
+  //
+  // This plugin runs INSIDE the agent-workspace container, which is
+  // deliberately OUTSIDE the etcd service mesh: it holds no registry client,
+  // no etcd credentials, and no service identity of its own. So
+  // `MEMORY_API_URL` is an ORCHESTRATOR-INJECTED peer URL, not the retired
+  // `<SVC>_API_URL` discovery pattern that first-party in-mesh services must
+  // never use. The orchestrator resolves the peer FROM the registry and
+  // injects the resolved value into the container envelope; this is the only
+  // category of code allowed to read a peer URL from the environment.
+  //
+  // Absent ⇒ THROW (fail fast). Unlike the best-effort `session.idle`
+  // auto-commit hook, a memory tool that silently no-ops would drop data the
+  // agent believes it persisted. Memory is on or off for a deployment.
+  const baseUrl = process.env.MEMORY_API_URL?.trim();
+  if (!baseUrl) {
+    throw new Error(
+      'MEMORY_API_URL is not configured on this worker. The operator must ' +
+        'set it for xema_memory_* tools to work.',
+    );
+  }
+  const project = state.ctx.project;
+  if (!project || !project.projectId) {
+    throw new Error(
+      'Session memory requires a projectId in context.json; this session is ' +
+        'not bound to a project (orgId-only). Skip xema_memory_* tools here.',
+    );
+  }
+  const sessionId =
+    state.ctx.invocation.sessionId ?? state.ctx.invocation.runId ?? 'no-session';
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ''),
+    orgId: project.orgId,
+    projectId: project.projectId,
+    actorId: `xema:${state.ctx.invocation.role}`,
+    sessionId,
+    role: state.ctx.invocation.role,
+  };
+}
+
+function memoryApiHeaders(ctx: MemoryApiCtx): Record<string, string> {
+  // The worker authenticates with its per-allocation Keycloak service
+  // JWT, read fresh from the service-token file workspace-proxy writes.
+  // `readServiceToken` fails fast when the file is missing/empty.
+  return {
+    'Content-Type': 'application/json',
+    Authorization: serviceTokenAuthorizationHeader(),
+    'x-xema-org-id': ctx.orgId,
+    'x-project-id': ctx.projectId,
+    'x-actor-type': 'agent',
+    'x-actor-id': ctx.actorId,
+  };
+}
+
+export function buildXemaMemorySetTool(workspaceDir: string) {
+  return tool({
+    description:
+      'Persist a project-scoped memory that survives context compaction and ' +
+      'future sessions. Use sparingly — for durable preferences, decisions, ' +
+      'lessons, or patterns worth recalling next time. Do NOT use for ' +
+      'conversational context or task-local notes.',
+    args: SET_ARGS,
+    async execute(args) {
+      const ctx = resolveMemoryApiCtx(workspaceDir, 'xema_memory_set');
+      const originRef = args.tag
+        ? `session:${ctx.sessionId}:${args.tag}`
+        : `session:${ctx.sessionId}`;
+      const body: Record<string, unknown> = {
+        content: args.content,
+        type: args.kind ?? 'GENERAL',
+        source: ctx.actorId,
+        originType: 'SESSION',
+        originRef,
+      };
+      if (args.importance !== undefined) body.importance = args.importance;
+
+      const res = await fetch(`${ctx.baseUrl}/memories`, {
+        method: 'POST',
+        headers: memoryApiHeaders(ctx),
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (!res.ok) {
+        const errText = await res.text().catch(() => '');
+        throw new Error(
+          `memory-api rejected write (${res.status}): ${errText.slice(0, 400)}`,
+        );
+      }
+      const stored = (await res.json().catch(() => null)) as unknown;
+      return toJsonString({ stored, originRef });
+    },
+  });
+}
+
+export function buildXemaMemoryGetTool(workspaceDir: string) {
+  return tool({
+    description:
+      'Recall project-scoped memories written by earlier sessions or by ' +
+      'xema_memory_set. Returns the most relevant items subject to an ' +
+      'optional kind or tag filter. Read this BEFORE large decisions so ' +
+      'prior lessons and preferences inform the work.',
+    args: GET_ARGS,
+    async execute(args) {
+      const ctx = resolveMemoryApiCtx(workspaceDir, 'xema_memory_get');
+      const params = new URLSearchParams();
+      params.set('limit', String(args.limit ?? 20));
+      if (args.kind) params.set('type', args.kind as MemoryKind);
+      if (args.tag) params.set('originRefContains', `:${args.tag}`);
+
+      const res = await fetch(
+        `${ctx.baseUrl}/memories?${params.toString()}`,
+        {
+          method: 'GET',
+          headers: memoryApiHeaders(ctx),
+          signal: AbortSignal.timeout(10_000),
+        },
+      );
+      if (!res.ok) {
+        const errText = await res.text().catch(() => '');
+        throw new Error(
+          `memory-api rejected read (${res.status}): ${errText.slice(0, 400)}`,
+        );
+      }
+      const raw = (await res.json().catch(() => null)) as unknown;
+      return toJsonString(raw ?? []);
+    },
+  });
+}