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

npm install
npm run build

Development

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:

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.