@mojoaar/opencode-mimir 0.26.0 → 0.29.1

package/dist/args.d.ts

@@ -8,5 +8,23 @@ export type IngestArgs = {
     dryRun: boolean;
     help: boolean;
 };
-/** Hand-rolled on purpose: three value flags do not justify a dependency. */
-export declare function parseArgs(argv: string[]): IngestArgs;
+export type SearchArgs = {
+    command: 'search';
+    query: string;
+    project?: string;
+    limit?: number;
+    url?: string;
+    token?: string;
+    help: boolean;
+};
+export type ExportArgs = {
+    command: 'export';
+    project?: string;
+    out?: string;
+    url?: string;
+    token?: string;
+    help: boolean;
+};
+export type Args = IngestArgs | SearchArgs | ExportArgs;
+/** Hand-rolled on purpose: five value flags do not justify a dependency. */
+export declare function parseArgs(argv: string[]): Args;

package/dist/args.js

@@ -1,47 +1,68 @@
-const VALUE_FLAGS = new Set(['project', 'url', 'token']);
-/** Hand-rolled on purpose: three value flags do not justify a dependency. */
+const VALUE_FLAGS = new Set(['project', 'url', 'token', 'limit', 'out']);
+/** Hand-rolled on purpose: five value flags do not justify a dependency. */
 export function parseArgs(argv) {
-    const args = {
-        command: 'ingest',
-        path: '.',
-        all: false,
-        dryRun: false,
-        help: argv.length === 0,
-    };
-    for (let i = 0; i < argv.length; i++) {
-        const token = argv[i];
-        if (token === 'ingest' || token === 'import')
+    const first = argv[0];
+    const command = first === 'search' ? 'search' : first === 'export' ? 'export' : 'ingest';
+    const rest = command === 'ingest' ? argv : argv.slice(1);
+    let path = '.';
+    let query = '';
+    let all = false;
+    let dryRun = false;
+    let help = argv.length === 0;
+    let project;
+    let url;
+    let token;
+    let out;
+    let limit;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === 'ingest' || arg === 'import' || arg === 'search' || arg === 'export')
             continue;
-        if (token === '-h' || token === '--help') {
-            args.help = true;
+        if (arg === '-h' || arg === '--help') {
+            help = true;
             continue;
         }
-        if (token === '--all') {
-            args.all = true;
+        if (arg === '--all') {
+            all = true;
             continue;
         }
-        if (token === '--dry-run') {
-            args.dryRun = true;
+        if (arg === '--dry-run') {
+            dryRun = true;
             continue;
         }
-        if (token.startsWith('--')) {
-            const body = token.slice(2);
+        if (arg.startsWith('--')) {
+            const body = arg.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);
+            const value = equals === -1 ? rest[++i] : body.slice(equals + 1);
             if (value === undefined || value.startsWith('--'))
                 throw new Error(`--${name} needs a value`);
             if (name === 'project')
-                args.project = value;
+                project = value;
             if (name === 'url')
-                args.url = value;
+                url = value;
             if (name === 'token')
-                args.token = value;
+                token = value;
+            if (name === 'out')
+                out = value;
+            if (name === 'limit') {
+                const size = Number(value);
+                if (!Number.isInteger(size) || size < 1)
+                    throw new Error('--limit needs a whole number');
+                limit = size;
+            }
             continue;
         }
-        args.path = token;
+        if (command === 'search')
+            query = arg;
+        else if (command === 'ingest')
+            path = arg;
     }
-    return args;
+    if (command === 'search')
+        return { command, query, project, limit, url, token, help };
+    if (command === 'export')
+        return { command, project, out, url, token, help };
+    return { command, path, project, url, token, all, dryRun, help };
 }

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { type IngestArgs } from './args.js';
+import { type ExportArgs, type IngestArgs, type SearchArgs } from './args.js';
 export type IngestIo = {
     out: (line: string) => void;
     err: (line: string) => void;
@@ -10,4 +10,6 @@ export type IngestIo = {
  * is testable and a caller can decide what a partial import means.
  */
 export declare function runIngest(args: IngestArgs, io: IngestIo): Promise<number>;
+export declare function runSearch(args: SearchArgs, io: IngestIo): Promise<number>;
+export declare function runExport(args: ExportArgs, io: IngestIo): Promise<number>;
 export declare function main(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, stat, writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { parseArgs } from './args.js';
 import { batchFiles } from './batch.js';
-import { callTool, detectRepo } from './client.js';
+import { callRoute, callTool, detectRepo } from './client.js';
 import { selectFiles } from './select.js';
-const USAGE = `mimir ingest — load a project's documentation into Mimir
+const USAGE = `mimir — long-term memory for an agent
 
-  mimir ingest [path] [options]
+  mimir ingest [path] [options]      load a project's documentation
+  mimir search <query> [options]     search every project you can read
+  mimir export [options]            write a project out as one markdown file
 
   --project <name>  name the project yourself. Required for a folder that is
-                    not a git repository; also keeps two folders apart.
+                    not a git repository, and for export.
   --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
+  --limit <n>       search: how many hits to ask for
+  --out <file>      export: where to write it (default: <project>.md)
 
 A git checkout imports into the project your agents already write to. Imports
 land under import/, where memory_search finds them.`;
@@ -108,6 +112,102 @@ export async function runIngest(args, io) {
     }
     return failed > 0 || skipped.length > 0 || walk.truncated ? 1 : 0;
 }
+/** One place for a readable failure: the message, then exit code 1. */
+function failed(io, message) {
+    io.err(message);
+    return 1;
+}
+async function projectSlugs(args) {
+    const listed = await callTool('project_list', {}, { url: args.url, token: args.token, timeoutMs: 5000 });
+    if (!listed.ok || !Array.isArray(listed.result))
+        return [];
+    return listed.result
+        .map((row) => {
+        const slug = row?.slug;
+        return typeof slug === 'string' ? slug : null;
+    })
+        .filter((slug) => slug !== null);
+}
+/** A bare "not found" is useless when the answer is one flag away. */
+async function askWhichProject(io, args) {
+    const available = await projectSlugs(args);
+    io.err('Pick one of:');
+    if (available.length === 0)
+        io.err('  (no projects yet, so write one memory first)');
+    for (const slug of available)
+        io.err(`  ${slug}`);
+    io.err('then pass --project <name>');
+    return 1;
+}
+export async function runSearch(args, io) {
+    if (args.help) {
+        io.out(USAGE);
+        return 0;
+    }
+    if (args.query.trim() === '') {
+        return failed(io, 'pass a query, for example: mimir search "rotate the keys"');
+    }
+    const response = await callRoute('/api/v1/search', {
+        method: 'POST',
+        body: {
+            query: args.query,
+            ...(args.project ? { project: args.project } : {}),
+            ...(args.limit ? { limit: args.limit } : {}),
+        },
+        url: args.url,
+        token: args.token,
+    });
+    if (!response.ok)
+        return failed(io, response.error);
+    let hits;
+    try {
+        const parsed = JSON.parse(response.body);
+        hits = Array.isArray(parsed.results) ? parsed.results : [];
+    }
+    catch {
+        return failed(io, 'mimir answered something that was not search results');
+    }
+    if (hits.length === 0) {
+        io.out('Nothing matches that in Mimir.');
+        return 0;
+    }
+    for (const hit of hits) {
+        const path = typeof hit.path === 'string' ? hit.path : '';
+        const title = typeof hit.title === 'string' ? hit.title : '';
+        // Without --project the same path can exist in several projects, so the
+        // line has to say which one it came from.
+        const where = args.project
+            ? path
+            : `${typeof hit.projectSlug === 'string' ? hit.projectSlug : '?'}: ${path}`;
+        io.out(title ? `${where} - ${title}` : where);
+    }
+    return 0;
+}
+export async function runExport(args, io) {
+    if (args.help) {
+        io.out(USAGE);
+        return 0;
+    }
+    if (!args.project) {
+        io.err('export needs a project: the file is named after it');
+        return askWhichProject(io, args);
+    }
+    const response = await callRoute(`/api/v1/projects/${encodeURIComponent(args.project)}/export`, {
+        url: args.url,
+        token: args.token,
+    });
+    if (!response.ok)
+        return failed(io, response.error);
+    const target = args.out ?? `${args.project}.md`;
+    try {
+        await writeFile(resolve(io.cwd, target), response.body, 'utf8');
+    }
+    catch (error) {
+        return failed(io, error.message);
+    }
+    io.out(`${Buffer.byteLength(response.body, 'utf8')} bytes written to ${target}`);
+    return 0;
+}
 export async function main(argv) {
     let args;
     try {
@@ -119,9 +219,15 @@ export async function main(argv) {
         process.exitCode = 2;
         return;
     }
-    process.exitCode = await runIngest(args, {
+    const io = {
         out: (line) => console.log(line),
         err: (line) => console.error(line),
         cwd: process.cwd(),
-    });
+    };
+    if (args.command === 'search')
+        process.exitCode = await runSearch(args, io);
+    else if (args.command === 'export')
+        process.exitCode = await runExport(args, io);
+    else
+        process.exitCode = await runIngest(args, io);
 }

package/dist/client.d.ts

@@ -5,6 +5,13 @@ export type CallResult = {
     ok: false;
     error: string;
 };
+export type RouteResult = {
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    error: string;
+};
 export type CallOptions = {
     url?: string;
     token?: string;
@@ -18,3 +25,11 @@ export type CallOptions = {
 export declare function callTool(name: string, args: Record<string, unknown>, options?: CallOptions): Promise<CallResult>;
 /** A repo key for X-Mimir-Repo, from MIMIR_REPO or `git remote get-url origin`. */
 export declare function detectRepo(directory: string): string | null;
+/**
+ * Calls one of the REST routes, for the CLI commands that need a whole file
+ * rather than a tool result. Same fail-soft contract as callTool.
+ */
+export declare function callRoute(path: string, options?: CallOptions & {
+    method?: 'GET' | 'POST';
+    body?: unknown;
+}): Promise<RouteResult>;

package/dist/client.js

@@ -1,4 +1,8 @@
 import { execFileSync } from 'node:child_process';
+function missingConfig(url, token) {
+    const missing = [url ? null : 'MIMIR_URL', token ? null : 'MIMIR_TOKEN'].filter(Boolean);
+    return `set ${missing.join(' and ')}`;
+}
 /**
  * Calls one Mimir MCP tool. Never throws: a plugin must not break a session
  * because the memory server is down.
@@ -7,7 +11,7 @@ export async function callTool(name, args, options = {}) {
     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' };
+        return { ok: false, error: missingConfig(url, token) };
     try {
         const response = await (options.fetch ?? fetch)(`${url}/mcp`, {
             method: 'POST',
@@ -60,3 +64,43 @@ export function detectRepo(directory) {
         return null;
     }
 }
+/**
+ * Calls one of the REST routes, for the CLI commands that need a whole file
+ * rather than a tool result. Same fail-soft contract as callTool.
+ */
+export async function callRoute(path, options = {}) {
+    const url = (options.url ?? process.env.MIMIR_URL ?? '').replace(/\/+$/, '');
+    const token = options.token ?? process.env.MIMIR_TOKEN ?? '';
+    if (!url || !token)
+        return { ok: false, error: missingConfig(url, token) };
+    try {
+        const response = await (options.fetch ?? fetch)(`${url}${path}`, {
+            method: options.method ?? 'GET',
+            headers: {
+                ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
+                authorization: `Bearer ${token}`,
+            },
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            // The API answers { error, code }; a proxy may answer HTML. Prefer the
+            // sentence when there is one, never a stack trace.
+            let message = `mimir responded ${response.status}`;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed.error === 'string')
+                    message = parsed.error;
+            }
+            catch {
+                // keep the status line
+            }
+            return { ok: false, error: message };
+        }
+        return { ok: true, body: text };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : 'request failed' };
+    }
+}

package/dist/tools.d.ts

@@ -2,7 +2,10 @@ import type { MimirConfig } from './config.js';
 export type Registration = {
     dispose: () => Promise<void>;
 };
-type ToolExecutor = (input: any, context: any) => Promise<{
+type ToolContext = {
+    sessionID?: string;
+} | undefined;
+type ToolExecutor = (input: unknown, context: ToolContext) => Promise<{
     content: string;
 }>;
 type ToolDefinition = {

package/dist/tools.js

@@ -13,6 +13,7 @@ export async function registerTools(ctx, config, repo) {
         editor.add(digestTool(repo));
         editor.add(rememberTool(repo));
         editor.add(searchTool(repo));
+        editor.add(readTool(repo));
         editor.add(learnTool(repo));
     });
 }
@@ -55,7 +56,8 @@ function digestTool(repo) {
             additionalProperties: false,
         },
         async execute(input) {
-            const result = await callTool('memory_digest', { budget_tokens: input?.budget_tokens ?? 800, repo: repo ?? undefined }, { timeoutMs: 5000 });
+            const args = input;
+            const result = await callTool('memory_digest', { budget_tokens: Number(args.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;
@@ -63,6 +65,9 @@ function digestTool(repo) {
         },
     };
 }
+// A project created from a repo a teammate already knows about splits the
+// knowledge in two until someone asks the owner for a grant.
+const NEW_PROJECT = ' Started a new project. If a teammate already uses this repository, request access at /app/requests on your Mimir install.';
 function rememberTool(repo) {
     return {
         name: 'mimir_remember',
@@ -72,6 +77,7 @@ function rememberTool(repo) {
             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' },
+                title: { type: 'string', description: 'One line. Defaults to the first line of the body.' },
                 kind: {
                     type: 'string',
                     enum: ['note', 'fact', 'decision', 'gotcha', 'procedure', 'snippet', 'import'],
@@ -82,10 +88,12 @@ function rememberTool(repo) {
         },
         // `client` and `session` are provenance, so history can say who wrote it.
         async execute(input, context) {
+            const args = input;
             const result = await callTool('memory_write', {
-                path: input.path,
-                body: input.body,
-                kind: input.kind,
+                path: String(args.path ?? ''),
+                body: String(args.body ?? ''),
+                title: typeof args.title === 'string' ? args.title : undefined,
+                kind: typeof args.kind === 'string' ? args.kind : undefined,
                 repo: repo ?? undefined,
                 client: 'opencode',
                 session: context?.sessionID,
@@ -93,7 +101,10 @@ function rememberTool(repo) {
             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}.` };
+            const note = written.projectCreated ? NEW_PROJECT : '';
+            return {
+                content: `${written.created ? 'Stored' : 'Updated'} ${written.path ?? String(args.path ?? '')}.${note}`,
+            };
         },
     };
 }
@@ -111,7 +122,8 @@ function searchTool(repo) {
             additionalProperties: false,
         },
         async execute(input) {
-            const result = await callTool('memory_search', { query: input?.query, path_prefix: input?.path_prefix, repo: repo ?? undefined }, { timeoutMs: 8000 });
+            const args = input;
+            const result = await callTool('memory_search', { query: typeof args.query === 'string' ? args.query : '', path_prefix: typeof args.path_prefix === 'string' ? args.path_prefix : undefined, repo: repo ?? undefined }, { timeoutMs: 8000 });
             if (!result.ok)
                 return { content: `Mimir is unavailable (${result.error}). Carry on without it.` };
             const hits = result.result;
@@ -125,6 +137,31 @@ function searchTool(repo) {
         },
     };
 }
+/** The date is what tells a reader whether the body still holds. */
+function renderMemory(memory) {
+    const day = typeof memory.updatedAt === 'string' ? memory.updatedAt.slice(0, 10) : '';
+    const head = day ? `${memory.path ?? ''} · updated ${day}` : (memory.path ?? '');
+    return `${head}\n# ${memory.title ?? ''}\n\n${memory.body ?? ''}`;
+}
+function readTool(repo) {
+    return {
+        name: 'mimir_read',
+        description: 'Read one memory in full by its path. Search returns paths and summaries; this is the body behind one.',
+        input: {
+            type: 'object',
+            properties: { path: { type: 'string', description: 'e.g. deploy/rollback' } },
+            required: ['path'],
+            additionalProperties: false,
+        },
+        async execute(input) {
+            const args = input;
+            const result = await callTool('memory_read', { path: String(args.path ?? ''), repo: repo ?? undefined }, { timeoutMs: 8000 });
+            if (!result.ok)
+                return { content: 'Nothing is stored at that path.' };
+            return { content: renderMemory(result.result) };
+        },
+    };
+}
 function learnTool(repo) {
     return {
         name: 'mimir_learn',
@@ -139,9 +176,10 @@ function learnTool(repo) {
             additionalProperties: false,
         },
         async execute(input, context) {
+            const args = input;
             const result = await callTool('memory_learn', {
-                transcript: input?.transcript,
-                hint: input?.hint,
+                transcript: String(args.transcript ?? ''),
+                hint: typeof args.hint === 'string' ? args.hint : undefined,
                 repo: repo ?? undefined,
                 client: 'opencode',
                 session: context?.sessionID,
@@ -149,10 +187,14 @@ function learnTool(repo) {
             if (!result.ok)
                 return { content: `Could not hand that over (${result.error}).` };
             const queued = result.result;
+            if (queued.queued) {
+                return {
+                    content: `Queued. The model writes the memories in the background.${queued.projectCreated ? NEW_PROJECT : ''}`,
+                };
+            }
+            // A refusal is a fact the agent should act on, not a failure to retry.
             return {
-                content: queued.queued
-                    ? 'Queued. The model writes the memories in the background.'
-                    : 'Mimir took no job: its queue is not running.',
+                content: typeof queued.reason === 'string' ? queued.reason : 'Mimir took no job: its queue is not running.',
             };
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojoaar/opencode-mimir",
-  "version": "0.26.0",
+  "version": "0.29.1",
   "description": "Mimir long-term memory for OpenCode sessions",
   "type": "module",
   "main": "src/index.ts",

package/src/args.ts

@@ -9,47 +9,85 @@ export type IngestArgs = {
   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,
-  }
+export type SearchArgs = {
+  command: 'search'
+  query: string
+  project?: string
+  limit?: number
+  url?: string
+  token?: string
+  help: boolean
+}
+
+export type ExportArgs = {
+  command: 'export'
+  project?: string
+  out?: string
+  url?: string
+  token?: string
+  help: boolean
+}
+
+export type Args = IngestArgs | SearchArgs | ExportArgs
+
+const VALUE_FLAGS = new Set(['project', 'url', 'token', 'limit', 'out'])
+
+/** Hand-rolled on purpose: five value flags do not justify a dependency. */
+export function parseArgs(argv: string[]): Args {
+  const first = argv[0]
+  const command: Args['command'] =
+    first === 'search' ? 'search' : first === 'export' ? 'export' : 'ingest'
+  const rest = command === 'ingest' ? argv : argv.slice(1)
+
+  let path = '.'
+  let query = ''
+  let all = false
+  let dryRun = false
+  let help = argv.length === 0
+  let project: string | undefined
+  let url: string | undefined
+  let token: string | undefined
+  let out: string | undefined
+  let limit: number | undefined
 
-  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
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i] as string
+    if (arg === 'ingest' || arg === 'import' || arg === 'search' || arg === 'export') continue
+    if (arg === '-h' || arg === '--help') {
+      help = true
       continue
     }
-    if (token === '--all') {
-      args.all = true
+    if (arg === '--all') {
+      all = true
       continue
     }
-    if (token === '--dry-run') {
-      args.dryRun = true
+    if (arg === '--dry-run') {
+      dryRun = true
       continue
     }
-    if (token.startsWith('--')) {
-      const body = token.slice(2)
+    if (arg.startsWith('--')) {
+      const body = arg.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)
+      const value = equals === -1 ? rest[++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
+      if (name === 'project') project = value
+      if (name === 'url') url = value
+      if (name === 'token') token = value
+      if (name === 'out') out = value
+      if (name === 'limit') {
+        const size = Number(value)
+        if (!Number.isInteger(size) || size < 1) throw new Error('--limit needs a whole number')
+        limit = size
+      }
       continue
     }
-    args.path = token
+    if (command === 'search') query = arg
+    else if (command === 'ingest') path = arg
   }
 
-  return args
+  if (command === 'search') return { command, query, project, limit, url, token, help }
+  if (command === 'export') return { command, project, out, url, token, help }
+  return { command, path, project, url, token, all, dryRun, help }
 }

package/src/cli.ts

@@ -1,22 +1,26 @@
 #!/usr/bin/env node
-import { readFile, stat } from 'node:fs/promises'
+import { readFile, stat, writeFile } from 'node:fs/promises'
 import { basename, join, resolve } from 'node:path'
 
-import { parseArgs, type IngestArgs } from './args.js'
+import { parseArgs, type Args, type ExportArgs, type IngestArgs, type SearchArgs } from './args.js'
 import { batchFiles } from './batch.js'
-import { callTool, detectRepo } from './client.js'
+import { callRoute, callTool, detectRepo } from './client.js'
 import { selectFiles } from './select.js'
 
-const USAGE = `mimir ingest — load a project's documentation into Mimir
+const USAGE = `mimir — long-term memory for an agent
 
-  mimir ingest [path] [options]
+  mimir ingest [path] [options]      load a project's documentation
+  mimir search <query> [options]     search every project you can read
+  mimir export [options]            write a project out as one markdown file
 
   --project <name>  name the project yourself. Required for a folder that is
-                    not a git repository; also keeps two folders apart.
+                    not a git repository, and for export.
   --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
+  --limit <n>       search: how many hits to ask for
+  --out <file>      export: where to write it (default: <project>.md)
 
 A git checkout imports into the project your agents already write to. Imports
 land under import/, where memory_search finds them.`
@@ -134,8 +138,108 @@ export async function runIngest(args: IngestArgs, io: IngestIo): Promise<number>
   return failed > 0 || skipped.length > 0 || walk.truncated ? 1 : 0
 }
 
+/** One place for a readable failure: the message, then exit code 1. */
+function failed(io: IngestIo, message: string): number {
+  io.err(message)
+  return 1
+}
+
+async function projectSlugs(args: { url?: string; token?: string }): Promise<string[]> {
+  const listed = await callTool('project_list', {}, { url: args.url, token: args.token, timeoutMs: 5000 })
+  if (!listed.ok || !Array.isArray(listed.result)) return []
+  return listed.result
+    .map((row) => {
+      const slug = (row as { slug?: unknown } | null)?.slug
+      return typeof slug === 'string' ? slug : null
+    })
+    .filter((slug): slug is string => slug !== null)
+}
+
+/** A bare "not found" is useless when the answer is one flag away. */
+async function askWhichProject(io: IngestIo, args: { url?: string; token?: string }): Promise<number> {
+  const available = await projectSlugs(args)
+  io.err('Pick one of:')
+  if (available.length === 0) io.err('  (no projects yet, so write one memory first)')
+  for (const slug of available) io.err(`  ${slug}`)
+  io.err('then pass --project <name>')
+  return 1
+}
+
+export async function runSearch(args: SearchArgs, io: IngestIo): Promise<number> {
+  if (args.help) {
+    io.out(USAGE)
+    return 0
+  }
+  if (args.query.trim() === '') {
+    return failed(io, 'pass a query, for example: mimir search "rotate the keys"')
+  }
+
+  const response = await callRoute('/api/v1/search', {
+    method: 'POST',
+    body: {
+      query: args.query,
+      ...(args.project ? { project: args.project } : {}),
+      ...(args.limit ? { limit: args.limit } : {}),
+    },
+    url: args.url,
+    token: args.token,
+  })
+  if (!response.ok) return failed(io, response.error)
+
+  let hits: Array<{ path?: unknown; title?: unknown; projectSlug?: unknown }>
+  try {
+    const parsed = JSON.parse(response.body) as { results?: unknown }
+    hits = Array.isArray(parsed.results) ? (parsed.results as typeof hits) : []
+  } catch {
+    return failed(io, 'mimir answered something that was not search results')
+  }
+
+  if (hits.length === 0) {
+    io.out('Nothing matches that in Mimir.')
+    return 0
+  }
+
+  for (const hit of hits) {
+    const path = typeof hit.path === 'string' ? hit.path : ''
+    const title = typeof hit.title === 'string' ? hit.title : ''
+    // Without --project the same path can exist in several projects, so the
+    // line has to say which one it came from.
+    const where = args.project
+      ? path
+      : `${typeof hit.projectSlug === 'string' ? hit.projectSlug : '?'}: ${path}`
+    io.out(title ? `${where} - ${title}` : where)
+  }
+  return 0
+}
+
+export async function runExport(args: ExportArgs, io: IngestIo): Promise<number> {
+  if (args.help) {
+    io.out(USAGE)
+    return 0
+  }
+  if (!args.project) {
+    io.err('export needs a project: the file is named after it')
+    return askWhichProject(io, args)
+  }
+
+  const response = await callRoute(`/api/v1/projects/${encodeURIComponent(args.project)}/export`, {
+    url: args.url,
+    token: args.token,
+  })
+  if (!response.ok) return failed(io, response.error)
+
+  const target = args.out ?? `${args.project}.md`
+  try {
+    await writeFile(resolve(io.cwd, target), response.body, 'utf8')
+  } catch (error) {
+    return failed(io, (error as Error).message)
+  }
+  io.out(`${Buffer.byteLength(response.body, 'utf8')} bytes written to ${target}`)
+  return 0
+}
+
 export async function main(argv: string[]): Promise<void> {
-  let args: IngestArgs
+  let args: Args
   try {
     args = parseArgs(argv)
   } catch (error) {
@@ -144,9 +248,14 @@ export async function main(argv: string[]): Promise<void> {
     process.exitCode = 2
     return
   }
-  process.exitCode = await runIngest(args, {
+
+  const io: IngestIo = {
     out: (line) => console.log(line),
     err: (line) => console.error(line),
     cwd: process.cwd(),
-  })
+  }
+
+  if (args.command === 'search') process.exitCode = await runSearch(args, io)
+  else if (args.command === 'export') process.exitCode = await runExport(args, io)
+  else process.exitCode = await runIngest(args as IngestArgs, io)
 }

package/src/client.ts

@@ -1,6 +1,13 @@
 import { execFileSync } from 'node:child_process'
+function missingConfig(url: string, token: string): string {
+  const missing = [url ? null : 'MIMIR_URL', token ? null : 'MIMIR_TOKEN'].filter(Boolean)
+  return `set ${missing.join(' and ')}`
+}
+
 export type CallResult = { ok: true; result: unknown } | { ok: false; error: string }
 
+export type RouteResult = { ok: true; body: string } | { ok: false; error: string }
+
 export type CallOptions = {
   url?: string
   token?: string
@@ -19,7 +26,7 @@ export async function callTool(
 ): 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' }
+  if (!url || !token) return { ok: false, error: missingConfig(url, token) }
 
   try {
     const response = await (options.fetch ?? fetch)(`${url}/mcp`, {
@@ -74,3 +81,45 @@ export function detectRepo(directory: string): string | null {
     return null
   }
 }
+
+/**
+ * Calls one of the REST routes, for the CLI commands that need a whole file
+ * rather than a tool result. Same fail-soft contract as callTool.
+ */
+export async function callRoute(
+  path: string,
+  options: CallOptions & { method?: 'GET' | 'POST'; body?: unknown } = {},
+): Promise<RouteResult> {
+  const url = (options.url ?? process.env.MIMIR_URL ?? '').replace(/\/+$/, '')
+  const token = options.token ?? process.env.MIMIR_TOKEN ?? ''
+  if (!url || !token) return { ok: false, error: missingConfig(url, token) }
+
+  try {
+    const response = await (options.fetch ?? fetch)(`${url}${path}`, {
+      method: options.method ?? 'GET',
+      headers: {
+        ...(options.body === undefined ? {} : { 'content-type': 'application/json' }),
+        authorization: `Bearer ${token}`,
+      },
+      body: options.body === undefined ? undefined : JSON.stringify(options.body),
+      signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+    })
+
+    const text = await response.text()
+    if (!response.ok) {
+      // The API answers { error, code }; a proxy may answer HTML. Prefer the
+      // sentence when there is one, never a stack trace.
+      let message = `mimir responded ${response.status}`
+      try {
+        const parsed = JSON.parse(text) as { error?: unknown }
+        if (typeof parsed.error === 'string') message = parsed.error
+      } catch {
+        // keep the status line
+      }
+      return { ok: false, error: message }
+    }
+    return { ok: true, body: text }
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : 'request failed' }
+  }
+}

package/src/tools.ts

@@ -3,7 +3,9 @@ import type { MimirConfig } from './config.js'
 
 export type Registration = { dispose: () => Promise<void> }
 
-type ToolExecutor = (input: any, context: any) => Promise<{ content: string }>
+type ToolInput = Record<string, unknown>
+type ToolContext = { sessionID?: string } | undefined
+type ToolExecutor = (input: unknown, context: ToolContext) => Promise<{ content: string }>
 type ToolDefinition = {
   name: string
   description: string
@@ -37,6 +39,7 @@ export async function registerTools(
     editor.add(digestTool(repo))
     editor.add(rememberTool(repo))
     editor.add(searchTool(repo))
+    editor.add(readTool(repo))
     editor.add(learnTool(repo))
   })
 }
@@ -84,9 +87,10 @@ function digestTool(repo: string | null): ToolDefinition {
       additionalProperties: false,
     },
     async execute(input) {
+      const args = input as ToolInput
       const result = await callTool(
         'memory_digest',
-        { budget_tokens: input?.budget_tokens ?? 800, repo: repo ?? undefined },
+        { budget_tokens: Number(args.budget_tokens ?? 800), repo: repo ?? undefined },
         { timeoutMs: 5000 },
       )
       if (!result.ok) return { content: `Mimir is unavailable (${result.error}). Carry on without it.` }
@@ -96,6 +100,10 @@ function digestTool(repo: string | null): ToolDefinition {
   }
 }
 
+// A project created from a repo a teammate already knows about splits the
+// knowledge in two until someone asks the owner for a grant.
+const NEW_PROJECT = ' Started a new project. If a teammate already uses this repository, request access at /app/requests on your Mimir install.'
+
 function rememberTool(repo: string | null): ToolDefinition {
   return {
     name: 'mimir_remember',
@@ -106,6 +114,7 @@ function rememberTool(repo: string | null): ToolDefinition {
       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' },
+        title: { type: 'string', description: 'One line. Defaults to the first line of the body.' },
         kind: {
           type: 'string',
           enum: ['note', 'fact', 'decision', 'gotcha', 'procedure', 'snippet', 'import'],
@@ -116,12 +125,14 @@ function rememberTool(repo: string | null): ToolDefinition {
     },
     // `client` and `session` are provenance, so history can say who wrote it.
     async execute(input, context) {
+      const args = input as ToolInput
       const result = await callTool(
         'memory_write',
         {
-          path: input.path,
-          body: input.body,
-          kind: input.kind,
+          path: String(args.path ?? ''),
+          body: String(args.body ?? ''),
+          title: typeof args.title === 'string' ? args.title : undefined,
+          kind: typeof args.kind === 'string' ? args.kind : undefined,
           repo: repo ?? undefined,
           client: 'opencode',
           session: context?.sessionID,
@@ -129,8 +140,11 @@ function rememberTool(repo: string | null): ToolDefinition {
         { timeoutMs: 8000 },
       )
       if (!result.ok) return { content: `Could not store that (${result.error}).` }
-      const written = result.result as { path?: string; created?: boolean }
-      return { content: `${written.created ? 'Stored' : 'Updated'} ${written.path ?? input.path}.` }
+      const written = result.result as { path?: string; created?: boolean; projectCreated?: boolean }
+      const note = written.projectCreated ? NEW_PROJECT : ''
+      return {
+        content: `${written.created ? 'Stored' : 'Updated'} ${written.path ?? String(args.path ?? '')}.${note}`,
+      }
     },
   }
 }
@@ -150,9 +164,10 @@ function searchTool(repo: string | null): ToolDefinition {
       additionalProperties: false,
     },
     async execute(input) {
+      const args = input as ToolInput
       const result = await callTool(
         'memory_search',
-        { query: input?.query, path_prefix: input?.path_prefix, repo: repo ?? undefined },
+        { query: typeof args.query === 'string' ? args.query : '', path_prefix: typeof args.path_prefix === 'string' ? args.path_prefix : undefined, repo: repo ?? undefined },
         { timeoutMs: 8000 },
       )
       if (!result.ok) return { content: `Mimir is unavailable (${result.error}). Carry on without it.` }
@@ -167,6 +182,37 @@ function searchTool(repo: string | null): ToolDefinition {
   }
 }
 
+/** The date is what tells a reader whether the body still holds. */
+function renderMemory(memory: { path?: string; title?: string; body?: string; updatedAt?: string }): string {
+  const day = typeof memory.updatedAt === 'string' ? memory.updatedAt.slice(0, 10) : ''
+  const head = day ? `${memory.path ?? ''} · updated ${day}` : (memory.path ?? '')
+  return `${head}\n# ${memory.title ?? ''}\n\n${memory.body ?? ''}`
+}
+
+function readTool(repo: string | null): ToolDefinition {
+  return {
+    name: 'mimir_read',
+    description:
+      'Read one memory in full by its path. Search returns paths and summaries; this is the body behind one.',
+    input: {
+      type: 'object',
+      properties: { path: { type: 'string', description: 'e.g. deploy/rollback' } },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    async execute(input) {
+      const args = input as ToolInput
+      const result = await callTool(
+        'memory_read',
+        { path: String(args.path ?? ''), repo: repo ?? undefined },
+        { timeoutMs: 8000 },
+      )
+      if (!result.ok) return { content: 'Nothing is stored at that path.' }
+      return { content: renderMemory(result.result as { path?: string; title?: string; body?: string; updatedAt?: string }) }
+    },
+  }
+}
+
 function learnTool(repo: string | null): ToolDefinition {
   return {
     name: 'mimir_learn',
@@ -182,11 +228,12 @@ function learnTool(repo: string | null): ToolDefinition {
       additionalProperties: false,
     },
     async execute(input, context) {
+      const args = input as ToolInput
       const result = await callTool(
         'memory_learn',
         {
-          transcript: input?.transcript,
-          hint: input?.hint,
+          transcript: String(args.transcript ?? ''),
+          hint: typeof args.hint === 'string' ? args.hint : undefined,
           repo: repo ?? undefined,
           client: 'opencode',
           session: context?.sessionID,
@@ -194,11 +241,16 @@ function learnTool(repo: string | null): ToolDefinition {
         { timeoutMs: 8000 },
       )
       if (!result.ok) return { content: `Could not hand that over (${result.error}).` }
-      const queued = result.result as { queued?: boolean }
+      const queued = result.result as { queued?: boolean; reason?: string; projectCreated?: boolean }
+      if (queued.queued) {
+        return {
+          content: `Queued. The model writes the memories in the background.${queued.projectCreated ? NEW_PROJECT : ''}`,
+        }
+      }
+      // A refusal is a fact the agent should act on, not a failure to retry.
       return {
-        content: queued.queued
-          ? 'Queued. The model writes the memories in the background.'
-          : 'Mimir took no job: its queue is not running.',
+        content:
+          typeof queued.reason === 'string' ? queued.reason : 'Mimir took no job: its queue is not running.',
       }
     },
   }