@mojoaar/opencode-mimir 0.0.0-stage → 0.14.0

package/dist/tools.d.ts

@@ -0,0 +1,36 @@
+import type { MimirConfig } from './config.js';
+export type Registration = {
+    dispose: () => Promise<void>;
+};
+type ToolExecutor = (input: any, context: any) => Promise<{
+    content: string;
+}>;
+type ToolDefinition = {
+    name: string;
+    description: string;
+    input: Record<string, unknown>;
+    execute: ToolExecutor;
+};
+type ToolsContext = {
+    tool: {
+        transform: (callback: (editor: {
+            add: (tool: ToolDefinition) => void;
+        }) => void) => Promise<Registration>;
+    };
+    mcp: {
+        transform: (callback: (editor: {
+            list: () => readonly [string, {
+                type?: string;
+                url?: string;
+                disabled?: boolean;
+            }][];
+        }) => void) => Promise<Registration>;
+    };
+};
+/**
+ * The two tools exist for someone running the plugin without the MCP server.
+ * When an MCP server already answers at the same endpoint they would only
+ * duplicate its tools, so `auto` leaves them out.
+ */
+export declare function registerTools(ctx: ToolsContext, config: MimirConfig, repo: string | null): Promise<Registration>;
+export {};

package/dist/tools.js

@@ -0,0 +1,86 @@
+import { callTool } from './client.js';
+/**
+ * The two tools exist for someone running the plugin without the MCP server.
+ * When an MCP server already answers at the same endpoint they would only
+ * duplicate its tools, so `auto` leaves them out.
+ */
+export async function registerTools(ctx, config, repo) {
+    if (config.tools === 'never')
+        return IDLE;
+    if (config.tools === 'auto' && (await servedByMcp(ctx, config.url)))
+        return IDLE;
+    return ctx.tool.transform((editor) => {
+        editor.add(digestTool(repo));
+        editor.add(rememberTool(repo));
+    });
+}
+const IDLE = { dispose: async () => { } };
+async function servedByMcp(ctx, url) {
+    let found = false;
+    try {
+        const registration = await ctx.mcp.transform((editor) => {
+            found = editor
+                .list()
+                .some(([, server]) => server.type === 'remote' && !server.disabled && sameEndpoint(server.url, `${url}/mcp`));
+        });
+        await registration.dispose();
+    }
+    catch {
+        // A broken MCP entry must not cost the session its tools.
+        return false;
+    }
+    return found;
+}
+function sameEndpoint(actual, expected) {
+    return strip(actual) === strip(expected);
+}
+function strip(value) {
+    return (value ?? '').replace(/\/+$/, '');
+}
+function digestTool(repo) {
+    return {
+        name: 'mimir_digest',
+        description: 'Load what this project already knows from Mimir. Call once at the start of a session, before searching for anything.',
+        input: {
+            type: 'object',
+            properties: {
+                budget_tokens: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Rough size cap, default 800',
+                },
+            },
+            additionalProperties: false,
+        },
+        async execute(input) {
+            const result = await callTool('memory_digest', { budget_tokens: input?.budget_tokens ?? 800, repo: repo ?? undefined }, { timeoutMs: 5000 });
+            if (!result.ok)
+                return { content: `Mimir is unavailable (${result.error}). Carry on without it.` };
+            const digest = result.result;
+            return { content: digest.text?.trim() || 'Mimir has nothing stored for this project yet.' };
+        },
+    };
+}
+function rememberTool(repo) {
+    return {
+        name: 'mimir_remember',
+        description: 'Store one durable fact in Mimir. Use a path like "deploy/rollback" or "auth/token-rotation"; rewriting the same path replaces what was there.',
+        input: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Slash-separated memory path, e.g. deploy/rollback' },
+                body: { type: 'string', description: 'What to remember, written so it reads without the conversation' },
+                kind: { type: 'string', enum: ['note', 'fact', 'decision', 'gotcha', 'snippet'] },
+            },
+            required: ['path', 'body'],
+            additionalProperties: false,
+        },
+        async execute(input) {
+            const result = await callTool('memory_write', { path: input.path, body: input.body, kind: input.kind, repo: repo ?? undefined }, { timeoutMs: 8000 });
+            if (!result.ok)
+                return { content: `Could not store that (${result.error}).` };
+            const written = result.result;
+            return { content: `${written.created ? 'Stored' : 'Updated'} ${written.path ?? input.path}.` };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@mojoaar/opencode-mimir",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.14.0",
+  "description": "Mimir long-term memory for OpenCode sessions",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "mimir": "dist/bin.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "mcp",
+    "memory"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": ">=2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.1.4",
+    "typescript": "^5.9.0"
+  }
+}

package/src/args.ts

@@ -0,0 +1,55 @@
+export type IngestArgs = {
+  command: 'ingest'
+  path: string
+  project?: string
+  url?: string
+  token?: string
+  all: boolean
+  dryRun: boolean
+  help: boolean
+}
+
+const VALUE_FLAGS = new Set(['project', 'url', 'token'])
+
+/** Hand-rolled on purpose: three value flags do not justify a dependency. */
+export function parseArgs(argv: string[]): IngestArgs {
+  const args: IngestArgs = {
+    command: 'ingest',
+    path: '.',
+    all: false,
+    dryRun: false,
+    help: argv.length === 0,
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i] as string
+    if (token === 'ingest' || token === 'import') continue
+    if (token === '-h' || token === '--help') {
+      args.help = true
+      continue
+    }
+    if (token === '--all') {
+      args.all = true
+      continue
+    }
+    if (token === '--dry-run') {
+      args.dryRun = true
+      continue
+    }
+    if (token.startsWith('--')) {
+      const body = token.slice(2)
+      const equals = body.indexOf('=')
+      const name = equals === -1 ? body : body.slice(0, equals)
+      if (!VALUE_FLAGS.has(name)) throw new Error(`unknown flag --${name}`)
+      const value = equals === -1 ? argv[++i] : body.slice(equals + 1)
+      if (value === undefined || value.startsWith('--')) throw new Error(`--${name} needs a value`)
+      if (name === 'project') args.project = value
+      if (name === 'url') args.url = value
+      if (name === 'token') args.token = value
+      continue
+    }
+    args.path = token
+  }
+
+  return args
+}

package/src/batch.ts

@@ -0,0 +1,29 @@
+/**
+ * Batches are what the server will accept in one call: 100 files and 2 MB.
+ * Greedy and order-preserving, so a big repository becomes several requests
+ * instead of one rejected one.
+ */
+export type Batch<T> = { files: T[]; bytes: number }
+
+export function batchFiles<T extends { bytes: number }>(
+  files: T[],
+  maxFiles = 100,
+  maxBytes = 2 * 1024 * 1024,
+): Batch<T>[] {
+  const batches: Batch<T>[] = []
+  let current: Batch<T> = { files: [], bytes: 0 }
+
+  for (const file of files) {
+    const wouldOverflow =
+      current.files.length > 0 && (current.files.length >= maxFiles || current.bytes + file.bytes > maxBytes)
+    if (wouldOverflow) {
+      batches.push(current)
+      current = { files: [], bytes: 0 }
+    }
+    current.files.push(file)
+    current.bytes += file.bytes
+  }
+
+  if (current.files.length > 0) batches.push(current)
+  return batches
+}

package/src/bin.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// The published entrypoint. Kept separate from cli.ts so the command can be
+// imported by tests without running: npm installs a bin as a symlink, so a
+// `process.argv[1]` check here would never match `.bin/mimir` and the command
+// would exit 0 doing nothing.
+import { main } from './cli.js'
+
+void main(process.argv.slice(2))

package/src/cli.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { readFile, stat } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+
+import { parseArgs, type IngestArgs } from './args.js'
+import { batchFiles } from './batch.js'
+import { callTool, detectRepo } from './client.js'
+import { selectFiles } from './select.js'
+
+const USAGE = `mimir ingest — load a project's documentation into Mimir
+
+  mimir ingest [path] [options]
+
+  --project <name>  name the project yourself. Required for a folder that is
+                    not a git repository; also keeps two folders apart.
+  --url <url>       Mimir base URL (default: MIMIR_URL)
+  --token <token>   API key (default: MIMIR_TOKEN)
+  --all             import every text file, not just documentation
+  --dry-run         print what would be sent and send nothing
+
+A git checkout imports into the project your agents already write to. Imports
+land under import/, where memory_search finds them.`
+
+const MAX_BODY_BYTES = 262_144
+
+export type IngestIo = {
+  out: (line: string) => void
+  err: (line: string) => void
+  cwd: string
+}
+
+type Prepared = { path: string; body: string; bytes: number }
+type Skip = { path: string; reason: string }
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Returns the exit code instead of calling process.exit, so the whole command
+ * is testable and a caller can decide what a partial import means.
+ */
+export async function runIngest(args: IngestArgs, io: IngestIo): Promise<number> {
+  if (args.help) {
+    io.out(USAGE)
+    return 0
+  }
+
+  const root = resolve(io.cwd, args.path)
+  if (!(await isDirectory(root))) {
+    io.err(`no such directory: ${args.path}`)
+    return 2
+  }
+
+  const repo = args.project ? null : detectRepo(root)
+  if (!args.project && !repo) {
+    // Falling back to the folder name would merge two different `docs/` folders
+    // into one project and let the second silently overwrite the first.
+    io.err(`not a git repository: pass --project <name> to name this folder's project`)
+    return 2
+  }
+
+  const key = args.project ? { project: args.project } : { repo: repo as string }
+  const label = args.project ?? (repo as string)
+
+  const walk = await selectFiles(root, { all: args.all })
+  const skipped: Skip[] = [...walk.skipped]
+
+  // Read before deciding: the server caps the decoded body, and a Latin-1 file
+  // can pass the byte check on disk and still exceed it once decoded.
+  const prepared: Prepared[] = []
+  for (const file of walk.files) {
+    try {
+      const body = await readFile(join(root, file.path), 'utf8')
+      const bytes = Buffer.byteLength(body, 'utf8')
+      if (bytes > MAX_BODY_BYTES) {
+        skipped.push({ path: file.path, reason: `too large (${bytes} bytes)` })
+        continue
+      }
+      prepared.push({ path: file.path, body, bytes })
+    } catch (error) {
+      skipped.push({ path: file.path, reason: (error as Error).message })
+    }
+  }
+
+  const batches = batchFiles(prepared)
+  const totalBytes = prepared.reduce((sum, file) => sum + file.bytes, 0)
+
+  if (args.dryRun) {
+    io.out(`would import ${prepared.length} files (${totalBytes} bytes) into ${label} as import/<path>`)
+    for (const file of skipped) io.err(`skipped ${file.path}: ${file.reason}`)
+    if (walk.truncated) {
+      io.err(`the folder tree was larger than the walk limit; the list above is incomplete`)
+      return 1
+    }
+    return 0
+  }
+
+  let imported = 0
+  let failed = 0
+
+  for (const [index, batch] of batches.entries()) {
+    const result = await callTool(
+      'memory_ingest',
+      {
+        ...key,
+        path_prefix: 'import',
+        files: batch.files.map((file) => ({ path: file.path, body: file.body })),
+      },
+      { url: args.url, token: args.token, timeoutMs: 60_000 },
+    )
+    if (!result.ok) {
+      failed++
+      io.err(`batch ${index + 1} failed: ${result.error}`)
+      continue
+    }
+
+    const outcome = result.result as { written?: number; skipped?: Skip[] }
+    imported += outcome.written ?? batch.files.length
+    for (const entry of outcome.skipped ?? []) {
+      skipped.push({ path: entry.path, reason: entry.reason })
+    }
+  }
+
+  for (const file of skipped) io.err(`skipped ${file.path}: ${file.reason}`)
+  io.out(`imported ${imported} files, skipped ${skipped.length}`)
+  if (walk.truncated) {
+    io.err(`the folder tree was larger than the walk limit; not everything was considered`)
+  }
+  return failed > 0 || skipped.length > 0 || walk.truncated ? 1 : 0
+}
+
+export async function main(argv: string[]): Promise<void> {
+  let args: IngestArgs
+  try {
+    args = parseArgs(argv)
+  } catch (error) {
+    console.error((error as Error).message)
+    console.error(USAGE)
+    process.exitCode = 2
+    return
+  }
+  process.exitCode = await runIngest(args, {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+    cwd: process.cwd(),
+  })
+}

package/src/client.ts

@@ -0,0 +1,76 @@
+import { execFileSync } from 'node:child_process'
+export type CallResult = { ok: true; result: unknown } | { ok: false; error: string }
+
+export type CallOptions = {
+  url?: string
+  token?: string
+  timeoutMs?: number
+  fetch?: typeof fetch
+}
+
+/**
+ * Calls one Mimir MCP tool. Never throws: a plugin must not break a session
+ * because the memory server is down.
+ */
+export async function callTool(
+  name: string,
+  args: Record<string, unknown>,
+  options: CallOptions = {},
+): Promise<CallResult> {
+  const url = (options.url ?? process.env.MIMIR_URL ?? '').replace(/\/+$/, '')
+  const token = options.token ?? process.env.MIMIR_TOKEN ?? ''
+  if (!url || !token) return { ok: false, error: 'MIMIR_URL and MIMIR_TOKEN must be set' }
+
+  try {
+    const response = await (options.fetch ?? fetch)(`${url}/mcp`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'tools/call',
+        params: { name, arguments: args },
+      }),
+      signal: AbortSignal.timeout(options.timeoutMs ?? 3000),
+    })
+
+    if (!response.ok) return { ok: false, error: `mimir responded ${response.status}` }
+
+    const body = (await response.json()) as {
+      error?: { message?: string }
+      result?: { content?: Array<{ text?: string }>; isError?: boolean }
+    }
+
+    if (body.error) return { ok: false, error: body.error.message ?? 'mimir returned an error' }
+
+    const text = body.result?.content?.[0]?.text
+    if (body.result?.isError) return { ok: false, error: text ?? 'mimir returned an error' }
+    if (!text) return { ok: true, result: body.result ?? null }
+
+    try {
+      return { ok: true, result: JSON.parse(text) }
+    } catch {
+      return { ok: true, result: text }
+    }
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : 'request failed' }
+  }
+}
+
+/** A repo key for X-Mimir-Repo, from MIMIR_REPO or `git remote get-url origin`. */
+export function detectRepo(directory: string): string | null {
+  if (process.env.MIMIR_REPO) return process.env.MIMIR_REPO
+  try {
+    const remote = execFileSync('git', ['-C', directory, 'remote', 'get-url', 'origin'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return remote || null
+  } catch {
+    return null
+  }
+}

package/src/config.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export type ToolPolicy = 'auto' | 'always' | 'never'
+
+export type MimirConfig = { url: string; token: string; tools: ToolPolicy }
+
+const DEFAULT_TOKEN_FILE = join(homedir(), '.config/opencode/.secrets/mimir-token')
+
+/**
+ * Options win over the environment, which wins over the token file the MCP
+ * header already points at. Anything missing means "stay quiet": a plugin
+ * must never break a session it cannot reach Mimir from.
+ */
+export function resolveConfig(
+  options: Record<string, unknown>,
+  env: Record<string, string | undefined> = process.env,
+  readFile: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): MimirConfig | null {
+  const url = normaliseUrl(text(options.url) ?? text(env.MIMIR_URL))
+  const token =
+    text(options.token) ?? text(env.MIMIR_TOKEN) ?? readTokenFile(text(options.tokenFile), readFile)
+  if (!url || !token) return null
+
+  const policy = options.tools
+  return { url, token, tools: policy === 'always' || policy === 'never' ? policy : 'auto' }
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function readTokenFile(path: string | undefined, readFile: (path: string) => string): string | undefined {
+  try {
+    // readFileSync does not expand `~`, and every example we print uses one.
+    return text(readFile((path ?? DEFAULT_TOKEN_FILE).replace(/^~(?=$|\/)/, homedir())))
+  } catch {
+    return undefined
+  }
+}
+
+/** A base URL, because callers append `/mcp` themselves. */
+function normaliseUrl(value: string | undefined): string | undefined {
+  return text(value?.replace(/\/+$/, '').replace(/\/mcp$/, ''))
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+import { Plugin } from '@opencode/plugin'
+import { callTool, detectRepo } from './client.js'
+import { resolveConfig } from './config.js'
+import { registerTools } from './tools.js'
+
+export const DIGEST_HEADER = '## What this project already knows (Mimir)\n\n'
+
+/**
+ * One injection point and two tools. The hook is what puts the project's
+ * digest in front of the model before the first turn, so a session starts
+ * informed without spending a tool call. Everything here is fail-soft: a slow
+ * or missing Mimir must never hold up a session.
+ */
+export default Plugin.define({
+  id: 'mimir',
+  async setup(ctx) {
+    const config = resolveConfig(ctx.options)
+    if (!config) return
+
+    // A folder without a git remote still needs a stable key, or every write
+    // lands in a fresh project. The server maps absolute paths to `local:<hash>`.
+    const repo = detectRepo(ctx.location.directory) ?? ctx.location.directory
+    const seen = new Set<string>()
+
+    // The hook runs before every model dispatch, so a session is fetched once
+    // and then left alone.
+    const session = await ctx.session.hook('context', async (event) => {
+      if (seen.has(event.sessionID)) return
+      // One attempt per session: a failed digest must not be re-paid before
+      // every model dispatch, which is how often this hook runs.
+      seen.add(event.sessionID)
+
+      const result = await callTool(
+        'memory_digest',
+        { repo: repo ?? undefined, budget_tokens: 800 },
+        { ...config, timeoutMs: 1500 },
+      ).catch(() => null)
+
+      if (!result?.ok) return
+      const text = (result.result as { text?: string }).text?.trim()
+      if (!text) return
+
+      event.system.push({ type: 'text', text: `${DIGEST_HEADER}${text}` })
+    })
+
+    const tools = await registerTools(ctx, config, repo)
+
+    return async () => {
+      await tools.dispose()
+      await session.dispose()
+    }
+  },
+})