opencode-mem-agents 0.3.1 → 0.3.2

package/README.md

@@ -0,0 +1,97 @@
+# opencode-mem-agents
+
+Persistent local memory plugin for OpenCode with:
+
+- SQLite + FTS5 storage
+- Automatic tool-result capture
+- Team-scoped memory tools
+- Local dashboard UI
+- Request/response trace journal for observability
+
+## Runtime
+
+- Node.js `>=18`
+- Default worker: `http://127.0.0.1:37778`
+- Default DB: `~/.opencode-mem/opencode-mem.db`
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+## Development
+
+```bash
+npm run build
+npm test
+```
+
+## Worker API
+
+- `GET /api/health`
+- `GET /api/search`
+- `GET /api/timeline` (`format=text|json`)
+- `POST /api/observations/batch` (optional `project` filter enforced server-side)
+- `POST /api/memory/save`
+- `POST /api/session/tool-result`
+- `GET /api/context/session`
+- `GET /api/activity`
+- `GET /api/traces`
+
+All JSON responses include `traceId` for request correlation.
+
+## Architecture
+
+Worker internals are split for maintainability:
+
+- `src/worker/server.ts` - HTTP lifecycle, auth/CORS, routing dispatch
+- `src/worker/routes.ts` - request parsing + response shaping
+- `src/worker/repository.ts` - SQLite schema + query/write logic
+- `src/worker/http.ts` - transport helpers + boundary error handling
+- `src/worker/config.ts` - runtime config loading
+
+## Observability
+
+`/api/traces` returns recent inbound/outbound/error events from the worker trace journal.
+
+Trace payloads are:
+
+- redacted for sensitive keys (`authorization`, `token`, `password`, `secret`, `apiKey`, `cookie`)
+- redacted for common secret-like inline values in free text (`Bearer ...`, `sk-...`, `AKIA...`)
+- size-capped before persistence
+- pruned by age (`OPENCODE_MEM_TRACE_RETENTION_DAYS`, default `7`)
+
+Example:
+
+```bash
+curl "http://127.0.0.1:37778/api/traces?limit=50"
+```
+
+## Security Controls
+
+- Optional API auth token:
+  - set `OPENCODE_MEM_API_TOKEN`
+  - send `Authorization: Bearer <token>` on `/api/*` (except health/readiness)
+- Dashboard auth for protected endpoints:
+  - use the in-memory token button in the UI (`Set Token`)
+  - or open with `?token=...` or `#token=...` (token is stripped from URL on load)
+  - token is never persisted to localStorage/sessionStorage
+- CORS defaults to localhost origins only
+- Optional explicit CORS origin override:
+  - `OPENCODE_MEM_CORS_ORIGIN=https://your-origin.example`
+- 500 responses are intentionally generic (`Internal server error`) to avoid leaking internals
+
+## Reliability Controls
+
+- Buffered observations are persisted to process-scoped disk queues (`pending-observations-<pid>.json`)
+- Failed sends are retried from the persisted queue
+- Flush retries are bounded and delivery concurrency is capped
+- Tool-result writes are deduped using `(sessionId, callId, tool)` capture keys
+- Timeline queries resolve around the true anchor at scale (not bounded to a fixed first-window scan)
+- Context injection cache is scoped by `(sessionId, workflowId, agent, phase)` to prevent cross-session leakage
+
+## Build Artifacts
+
+The dashboard is built from `dashboard/` and embedded into `src/dashboard-html.ts` during `npm run build`.

package/dist/contracts.d.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+export declare const observationTypeSchema: z.ZodEnum<{
+    discovery: "discovery";
+    decision: "decision";
+    bugfix: "bugfix";
+    feature: "feature";
+    refactor: "refactor";
+    change: "change";
+    contract: "contract";
+    blocker: "blocker";
+    "test-result": "test-result";
+    "review-finding": "review-finding";
+}>;
+export declare const signalSchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+export declare const roleSchema: z.ZodEnum<{
+    default: "default";
+    lead: "lead";
+    backend: "backend";
+    frontend: "frontend";
+    database: "database";
+    test: "test";
+    security: "security";
+    reviewer: "reviewer";
+}>;
+export declare const searchOrderSchema: z.ZodEnum<{
+    created_desc: "created_desc";
+    created_asc: "created_asc";
+    id_desc: "id_desc";
+    id_asc: "id_asc";
+}>;
+export declare const searchParamsSchema: z.ZodObject<{
+    query: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    type: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodEnum<{
+        discovery: "discovery";
+        decision: "decision";
+        bugfix: "bugfix";
+        feature: "feature";
+        refactor: "refactor";
+        change: "change";
+        contract: "contract";
+        blocker: "blocker";
+        "test-result": "test-result";
+        "review-finding": "review-finding";
+    }>>>;
+    signal: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>>;
+    agent: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    dateStart: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    dateEnd: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    since_id: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    orderBy: z.ZodDefault<z.ZodEnum<{
+        created_desc: "created_desc";
+        created_asc: "created_asc";
+        id_desc: "id_desc";
+        id_asc: "id_asc";
+    }>>;
+}, z.core.$strip>;
+export declare const timelineParamsSchema: z.ZodObject<{
+    anchor: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    query: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    depth_before: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    depth_after: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    format: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDefault<z.ZodEnum<{
+        text: "text";
+        json: "json";
+    }>>>;
+}, z.core.$strip>;
+export declare const observationsBatchBodySchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodCoercedNumber<unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+}, z.core.$strip>;
+export declare const memorySaveBodySchema: z.ZodObject<{
+    sessionId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    type: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodEnum<{
+        discovery: "discovery";
+        decision: "decision";
+        bugfix: "bugfix";
+        feature: "feature";
+        refactor: "refactor";
+        change: "change";
+        contract: "contract";
+        blocker: "blocker";
+        "test-result": "test-result";
+        "review-finding": "review-finding";
+    }>>>;
+    title: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    text: z.ZodString;
+    facts: z.ZodDefault<z.ZodType<string[], unknown, z.core.$ZodTypeInternals<string[], unknown>>>;
+    narrative: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    concepts: z.ZodDefault<z.ZodType<string[], unknown, z.core.$ZodTypeInternals<string[], unknown>>>;
+    files_read: z.ZodDefault<z.ZodType<string[], unknown, z.core.$ZodTypeInternals<string[], unknown>>>;
+    files_modified: z.ZodDefault<z.ZodType<string[], unknown, z.core.$ZodTypeInternals<string[], unknown>>>;
+    agent: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    workflow_id: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    task_id: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    phase: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    signal: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        signal: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>>>;
+        agent: z.ZodOptional<z.ZodObject<{
+            agentName: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+            workflowId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+            taskId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+            phase: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const toolResultBodySchema: z.ZodObject<{
+    sessionId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    tool: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    callId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    args: z.ZodOptional<z.ZodUnknown>;
+    output: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    title: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    files_modified: z.ZodDefault<z.ZodType<string[], unknown, z.core.$ZodTypeInternals<string[], unknown>>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        signal: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>>>;
+        agent: z.ZodOptional<z.ZodObject<{
+            agentName: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+            workflowId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+            taskId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+            phase: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+        }, z.core.$strip>>;
+        timestamp: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const contextSessionParamsSchema: z.ZodObject<{
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    agent: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    sessionId: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+}, z.core.$strip>;
+export declare const activityParamsSchema: z.ZodObject<{
+    project: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+    since_id: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    role: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+}, z.core.$strip>;
+export declare const tracesParamsSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    trace_id: z.ZodType<string | undefined, unknown, z.core.$ZodTypeInternals<string | undefined, unknown>>;
+}, z.core.$strip>;
+export type SearchParams = z.infer<typeof searchParamsSchema>;
+export type TimelineParams = z.infer<typeof timelineParamsSchema>;
+export type ObservationsBatchBody = z.infer<typeof observationsBatchBodySchema>;
+export type MemorySaveBody = z.infer<typeof memorySaveBodySchema>;
+export type ToolResultBody = z.infer<typeof toolResultBodySchema>;
+export type ContextSessionParams = z.infer<typeof contextSessionParamsSchema>;
+export type ActivityParams = z.infer<typeof activityParamsSchema>;
+export type TracesParams = z.infer<typeof tracesParamsSchema>;

package/dist/contracts.js

@@ -0,0 +1,170 @@
+import { z } from "zod";
+function optionalString(max) {
+    return z.preprocess((value) => {
+        if (typeof value !== "string")
+            return value;
+        const trimmed = value.trim();
+        return trimmed === "" ? undefined : trimmed;
+    }, z.string().max(max).optional());
+}
+function optionalIsoDate() {
+    return optionalString(100).refine((value) => {
+        if (value === undefined)
+            return true;
+        return Number.isFinite(Date.parse(value));
+    }, "must be a valid ISO date string");
+}
+function optionalStringArray(maxItems, maxLength) {
+    return z.preprocess((value) => {
+        if (Array.isArray(value))
+            return value;
+        if (typeof value !== "string")
+            return [];
+        const trimmed = value.trim();
+        if (!trimmed)
+            return [];
+        try {
+            const parsed = JSON.parse(trimmed);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [trimmed];
+        }
+    }, z.array(z.string().trim().min(1).max(maxLength)).max(maxItems));
+}
+const observationTypeValues = [
+    "discovery",
+    "decision",
+    "bugfix",
+    "feature",
+    "refactor",
+    "change",
+    "contract",
+    "blocker",
+    "test-result",
+    "review-finding",
+];
+const signalValues = ["high", "medium", "low"];
+const roleValues = [
+    "lead",
+    "backend",
+    "frontend",
+    "database",
+    "test",
+    "security",
+    "reviewer",
+    "default",
+];
+export const observationTypeSchema = z.enum(observationTypeValues);
+export const signalSchema = z.enum(signalValues);
+export const roleSchema = z.enum(roleValues);
+export const searchOrderSchema = z.enum([
+    "created_desc",
+    "created_asc",
+    "id_desc",
+    "id_asc",
+]);
+export const searchParamsSchema = z
+    .object({
+    query: optionalString(512),
+    project: optionalString(512),
+    type: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? undefined : value), observationTypeSchema.optional()),
+    signal: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? undefined : value), signalSchema.optional()),
+    agent: optionalString(128),
+    dateStart: optionalIsoDate(),
+    dateEnd: optionalIsoDate(),
+    since_id: z.coerce.number().int().min(0).max(10_000_000).default(0),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    offset: z.coerce.number().int().min(0).max(100_000).default(0),
+    orderBy: searchOrderSchema.default("created_desc"),
+})
+    .refine((value) => {
+    if (!value.dateStart || !value.dateEnd)
+        return true;
+    return Date.parse(value.dateStart) <= Date.parse(value.dateEnd);
+}, {
+    message: "dateStart must be earlier than or equal to dateEnd",
+    path: ["dateStart"],
+});
+export const timelineParamsSchema = z.object({
+    anchor: z.preprocess((value) => (value === "" ? undefined : value), z.coerce.number().int().positive().optional()),
+    query: optionalString(512),
+    depth_before: z.coerce.number().int().min(0).max(100).default(10),
+    depth_after: z.coerce.number().int().min(0).max(100).default(10),
+    project: optionalString(512),
+    format: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? "text" : value), z.enum(["text", "json"]).default("text")),
+});
+export const observationsBatchBodySchema = z.object({
+    ids: z.array(z.coerce.number().int().positive()).min(1).max(200),
+    project: optionalString(512),
+});
+export const memorySaveBodySchema = z.object({
+    sessionId: optionalString(256),
+    project: optionalString(512),
+    type: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? undefined : value), observationTypeSchema.optional()),
+    title: optionalString(500),
+    text: z.string().trim().min(1).max(8192),
+    facts: optionalStringArray(200, 1024).default([]),
+    narrative: optionalString(4096),
+    concepts: optionalStringArray(200, 256).default([]),
+    files_read: optionalStringArray(500, 4096).default([]),
+    files_modified: optionalStringArray(500, 4096).default([]),
+    agent: optionalString(128),
+    workflow_id: optionalString(512),
+    task_id: optionalString(512),
+    phase: optionalString(256),
+    signal: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? undefined : value), signalSchema.optional()),
+    metadata: z
+        .object({
+        signal: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? undefined : value), signalSchema.optional()),
+        agent: z
+            .object({
+            agentName: optionalString(128),
+            workflowId: optionalString(512),
+            taskId: optionalString(512),
+            phase: optionalString(256),
+        })
+            .optional(),
+    })
+        .optional(),
+});
+export const toolResultBodySchema = z.object({
+    sessionId: optionalString(256),
+    project: optionalString(512),
+    tool: optionalString(100),
+    callId: optionalString(256),
+    args: z.unknown().optional(),
+    output: optionalString(8192),
+    title: optionalString(500),
+    files_modified: optionalStringArray(500, 4096).default([]),
+    metadata: z
+        .object({
+        signal: z.preprocess((value) => (typeof value === "string" && value.trim() === "" ? undefined : value), signalSchema.optional()),
+        agent: z
+            .object({
+            agentName: optionalString(128),
+            workflowId: optionalString(512),
+            taskId: optionalString(512),
+            phase: optionalString(256),
+        })
+            .optional(),
+        timestamp: z.coerce.number().int().positive().optional(),
+    })
+        .optional(),
+});
+export const contextSessionParamsSchema = z.object({
+    project: optionalString(512),
+    limit: z.coerce.number().int().min(1).max(100).default(10),
+    agent: optionalString(128),
+    sessionId: optionalString(256),
+});
+export const activityParamsSchema = z.object({
+    project: optionalString(512),
+    since_id: z.coerce.number().int().min(0).max(10_000_000).default(0),
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+    role: optionalString(64),
+});
+export const tracesParamsSchema = z.object({
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+    trace_id: optionalString(64),
+});