march-cli 0.1.24 → 0.1.26

package/src/memory/markdown-tools.mjs

@@ -1,103 +1,174 @@
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { toolText } from "../agent/tool-result.mjs";
-
-export function createMarkdownMemoryTools(store) {
-  if (!store) return [];
-  return [
-    defineTool({
-      name: "memory_search",
-      label: "Memory Search",
-      description:
-        "Search the Markdown memory vault using ripgrep. This is literal text search over memory Markdown files, not semantic search and not March's internal tags-only memory hint recall. Use it when memory hints are insufficient or you need to find a memory by phrase, term, or detail.",
-      parameters: Type.Object({
-        query: Type.String({ description: "Ripgrep query to search in Markdown memory files" }),
-        limit: Type.Optional(Type.Number({ description: "Maximum matching lines to return. Default: 20" })),
-      }),
-      execute: async (_toolCallId, params) => {
-        const results = store.searchRipgrep(params.query, { limit: params.limit ?? 20 });
-        if (results.length === 0) return toolText(formatMemorySearchMiss(params.query));
-        return toolText(results.map((result) => result.line).join("\n"), { results });
-      },
-    }),
-
-    defineTool({
-      name: "memory_open",
-      label: "Memory Open",
-      description: "Open a Markdown memory by id or by path. Use this after memory hint or memory_search when you need the full memory body. To edit an existing memory, use the returned path with edit_file for targeted edits.",
-      parameters: Type.Object({
-        id: Type.Optional(Type.String({ description: "Memory id from memory hint, e.g. mem_..." })),
-        path: Type.Optional(Type.String({ description: "Path returned by memory_search" })),
-      }),
-      execute: async (_toolCallId, params) => {
-        try {
-          const identifier = params.id || params.path;
-          const opened = store.open(identifier);
-          return toolText(
-            `path: ${opened.path}\nUse edit_file with this path for targeted edits.\n\n---\n${opened.content}`,
-            opened,
-          );
-        } catch (err) {
-          return toolText(`Error: ${err.message}`, { error: true });
-        }
-      },
-    }),
-
-    defineTool({
-      name: "memory_save",
-      label: "Memory Save",
-      description:
-        "Create a Markdown memory or update whole fields on an existing memory. For targeted edits to an existing memory body or frontmatter, use memory_open to get the path, then edit_file. Before creating a new memory, merge related updates into an existing memory when they share the same topic or decision thread. New memories require name, description, body, and at least one tag because memory hints only use tags. When updating by id, omitted fields keep their existing values; passing tags replaces the full tag list.",
-      parameters: Type.Object({
-        id: Type.Optional(Type.String({ description: "Existing memory id to update. Omit to create a new memory." })),
-        name: Type.Optional(Type.String({ description: "Memory name. Required when creating." })),
-        description: Type.Optional(Type.String({ description: "Short natural-language summary shown in memory hint. Required when creating." })),
-        body: Type.Optional(Type.String({ description: "Markdown memory body. Required when creating." })),
-        tags: Type.Optional(Type.Array(Type.String(), { description: "Tags used for memory hint. Required and non-empty when creating; replaces tags when updating. Prefer stable retrieval keys: project name, technology, feature/domain, user/person, and decision topic. Use lowercase kebab-case when possible. Use shared tags to keep related facts discoverable and merge them into one memory when they belong to the same topic. Examples: ['march-cli', 'tooling', 'permissions'], ['memory', 'sqlite-index']." })),
-      }),
-      execute: async (_toolCallId, params) => {
-        try {
-          const entry = store.save(params);
-          return toolText(
-            `Saved ${entry.id}\npath: ${entry.path}\ntags: ${entry.tags.join(", ")}`,
-            { memory: entry },
-          );
-        } catch (err) {
-          return toolText(`Error: ${err.message}`, { error: true });
-        }
-      },
-    }),
-
-    defineTool({
-      name: "memory_delete",
-      label: "Memory Delete",
-      description: "Soft-delete a Markdown memory by id or path. This marks status as deleted so memory hint and memory_search exclude it; the file remains on disk for audit/recovery.",
-      parameters: Type.Object({
-        id: Type.Optional(Type.String({ description: "Memory id to delete, e.g. mem_..." })),
-        path: Type.Optional(Type.String({ description: "Memory file path to delete" })),
-      }),
-      execute: async (_toolCallId, params) => {
-        try {
-          const identifier = params.id || params.path;
-          const result = store.delete(identifier);
-          if (result.alreadyDeleted) return toolText(`Memory ${result.id} is already deleted.\npath: ${result.path}`, { memory: result });
-          return toolText(`Deleted ${result.id}\npath: ${result.path}`, { memory: result });
-        } catch (err) {
-          return toolText(`Error: ${err.message}`, { error: true });
-        }
-      },
-    }),
-  ];
-}
-
-function formatMemorySearchMiss(query) {
-  const text = String(query ?? "");
-  const lines = [
-    `No memory files matched "${text}".`,
-    "memory_search is literal ripgrep over Markdown files; it is not semantic search and does not use memory-hint hints.",
-  ];
-  if (/^mem_[a-z0-9_\-]+$/i.test(text.trim())) {
-    lines.push("This looks like a memory id. Use memory_open({ id }) to open it directly.");
-  }
-  return lines.join("\n");
-}
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { toolText } from "../agent/tool-result.mjs";
+import { createRemoteMemoryClients } from "./remote/client.mjs";
+import { normalizeRemoteMemorySources } from "./remote/config.mjs";
+
+export function createMarkdownMemoryTools(store, { remoteSources = [] } = {}) {
+  if (!store) return [];
+  const remoteClients = createRemoteMemoryClients(normalizeRemoteMemorySources({ remoteMemories: remoteSources }));
+  return [
+    defineTool({
+      name: "memory_search",
+      label: "Memory Search",
+      description:
+        "Search Markdown memory sources. By default searches local memory. Use source='all' for local plus all remote memories, source='local' for local memory, or source='<remote-name>' for a configured remote memory. Supports ripgrep regex syntax; use syntax='literal' for exact text search.",
+      parameters: Type.Object({
+        query: Type.String({ description: "Ripgrep query/pattern to search in Markdown memory files" }),
+        source: Type.Optional(Type.String({ description: "Memory source: omitted/local, all, or a remote memory name" })),
+        syntax: Type.Optional(Type.Union([Type.Literal("regex"), Type.Literal("literal")], { description: "Pattern syntax. Default: regex" })),
+        case: Type.Optional(Type.Union([Type.Literal("smart"), Type.Literal("sensitive"), Type.Literal("insensitive")], { description: "Case matching mode. Default: smart" })),
+        context: Type.Optional(Type.Number({ description: "Context lines around each match. Default: 2" })),
+        glob: Type.Optional(Type.Array(Type.String(), { description: "Optional ripgrep glob filters, e.g. ['**/*.md']" })),
+        limit: Type.Optional(Type.Number({ description: "Maximum matches to return. Default: 20, max: 50" })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const source = String(params.source ?? "local").trim() || "local";
+          const results = await searchSources({ store, remoteClients, source, params });
+          if (results.length === 0) return toolText(formatMemorySearchMiss(params.query, source));
+          return toolText(formatMemorySearchResults(results, source), { results });
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+
+    defineTool({
+      name: "memory_open",
+      label: "Memory Open",
+      description: "Open a Markdown memory by id or by path. Use this after memory hint or memory_search when you need more context. Local memories may be edited with edit_file; remote memories are read-only.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Local memory id from memory hint, e.g. mem_..." })),
+        source: Type.Optional(Type.String({ description: "Memory source: omitted/local or a remote memory name" })),
+        path: Type.Optional(Type.String({ description: "Path returned by memory_search" })),
+        line: Type.Optional(Type.Number({ description: "Open around this 1-based line number" })),
+        context: Type.Optional(Type.Number({ description: "Context lines around line. Default: 40" })),
+        offset: Type.Optional(Type.Number({ description: "Open from this 1-based line number" })),
+        limit: Type.Optional(Type.Number({ description: "Maximum lines to return when using offset" })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const source = String(params.source ?? "local").trim() || "local";
+          if (source !== "local") {
+            const client = findRemoteClient(remoteClients, source);
+            if (!client) throw new Error(`unknown remote memory source: ${source}`);
+            if (!params.path) throw new Error("path is required for remote memory_open");
+            const opened = await client.open(params);
+            return toolText(formatRemoteOpen(opened), opened);
+          }
+          const identifier = params.id || params.path;
+          const opened = store.open(identifier, params);
+          return toolText(formatLocalOpen(opened), opened);
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+
+    defineTool({
+      name: "memory_save",
+      label: "Memory Save",
+      description:
+        "Create a Markdown memory or update whole fields on an existing memory. For targeted edits to an existing memory body or frontmatter, use memory_open to get the path, then edit_file. Before creating a new memory, merge related updates into an existing memory when they share the same topic or decision thread. New memories require name, description, body, and at least one tag because memory hints only use tags. When updating by id, omitted fields keep their existing values; passing tags replaces the full tag list.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Existing memory id to update. Omit to create a new memory." })),
+        name: Type.Optional(Type.String({ description: "Memory name. Required when creating." })),
+        description: Type.Optional(Type.String({ description: "Short natural-language summary shown in memory hint. Required when creating." })),
+        body: Type.Optional(Type.String({ description: "Markdown memory body. Required when creating." })),
+        tags: Type.Optional(Type.Array(Type.String(), { description: "Tags used for memory hint. Required and non-empty when creating; replaces tags when updating. Prefer stable retrieval keys: project name, technology, feature/domain, user/person, and decision topic. Use lowercase kebab-case when possible. Examples: ['march-cli', 'tooling', 'permissions'], ['memory', 'sqlite-index']." })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const entry = store.save(params);
+          return toolText(
+            `Saved ${entry.id}\npath: ${entry.path}\ntags: ${entry.tags.join(", ")}`,
+            { memory: entry },
+          );
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+
+    defineTool({
+      name: "memory_delete",
+      label: "Memory Delete",
+      description: "Soft-delete a local Markdown memory by id or path. Remote memories are read-only and cannot be deleted through this tool.",
+      parameters: Type.Object({
+        id: Type.Optional(Type.String({ description: "Memory id to delete, e.g. mem_..." })),
+        path: Type.Optional(Type.String({ description: "Memory file path to delete" })),
+      }),
+      execute: async (_toolCallId, params) => {
+        try {
+          const identifier = params.id || params.path;
+          const result = store.delete(identifier);
+          if (result.alreadyDeleted) return toolText(`Memory ${result.id} is already deleted.\npath: ${result.path}`, { memory: result });
+          return toolText(`Deleted ${result.id}\npath: ${result.path}`, { memory: result });
+        } catch (err) {
+          return toolText(`Error: ${err.message}`, { error: true });
+        }
+      },
+    }),
+  ];
+}
+
+async function searchSources({ store, remoteClients, source, params }) {
+  if (source === "local") return localSearch(store, params);
+  if (source === "all") {
+    const local = localSearch(store, params);
+    const remote = await Promise.all(remoteClients.map(async (client) => client.search(params)));
+    return [...local, ...remote.flat()].slice(0, normalizeLimit(params.limit));
+  }
+  const client = findRemoteClient(remoteClients, source);
+  if (!client) throw new Error(`unknown remote memory source: ${source}`);
+  return client.search(params);
+}
+
+function localSearch(store, params) {
+  return store.searchRipgrep(params.query, params).map((result) => ({ ...result, source: "local" }));
+}
+
+function findRemoteClient(clients, source) {
+  return clients.find((client) => client.name === source);
+}
+
+function formatMemorySearchResults(results, requestedSource) {
+  const scope = requestedSource === "all" ? "all memory sources" : requestedSource;
+  const lines = [`memory_search found ${results.length} match${results.length === 1 ? "" : "es"} in ${scope}.`];
+  results.forEach((result, index) => {
+    lines.push("", `[${index + 1}] ${result.source}: ${result.path}:${result.line}`);
+    if (result.excerpt?.text) lines.push(result.excerpt.text);
+    lines.push(`Open: memory_open source="${result.source}" path="${result.path}" line=${result.line}`);
+  });
+  return lines.join("\n");
+}
+
+function formatLocalOpen(opened) {
+  const range = opened.startLine && opened.endLine ? `lines: ${opened.startLine}-${opened.endLine}\n` : "";
+  return `path: ${opened.path}\n${range}Use edit_file with this path for targeted edits.\n\n---\n${opened.content}`;
+}
+
+function formatRemoteOpen(opened) {
+  const range = opened.startLine && opened.endLine ? `lines: ${opened.startLine}-${opened.endLine}\n` : "";
+  return `source: ${opened.source}\npath: ${opened.path}\n${range}Remote memory is read-only.\n\n---\n${opened.content}`;
+}
+
+function formatMemorySearchMiss(query, source) {
+  const text = String(query ?? "");
+  const where = source && source !== "local" ? ` in ${source}` : "";
+  const lines = [
+    `No memory files matched "${text}"${where}.`,
+    "memory_search is literal ripgrep over Markdown files; it is not semantic search and does not use memory-hint hints.",
+  ];
+  if (/^mem_[a-z0-9_\-]+$/i.test(text.trim())) {
+    lines.push("This looks like a memory id. Use memory_open({ id }) to open it directly.");
+  }
+  return lines.join("\n");
+}
+
+function normalizeLimit(limit) {
+  const number = Number(limit);
+  if (!Number.isFinite(number)) return 20;
+  return Math.min(50, Math.max(1, Math.floor(number)));
+}

package/src/memory/remote/client.mjs

@@ -0,0 +1,68 @@
+export class RemoteMemoryClient {
+  constructor({ name, url, token = null, fetchImpl = globalThis.fetch } = {}) {
+    if (!name) throw new Error("RemoteMemoryClient requires a source name");
+    if (!url) throw new Error("RemoteMemoryClient requires a URL");
+    if (typeof fetchImpl !== "function") throw new Error("fetch is not available for remote memory");
+    this.name = name;
+    this.url = String(url).replace(/\/$/, "");
+    this.token = token;
+    this.fetchImpl = fetchImpl;
+  }
+
+  async metadata() {
+    return this.#request("GET", "/metadata");
+  }
+
+  async search({ query, limit, context, syntax, case: caseMode, glob } = {}) {
+    const response = await this.#request("POST", "/search", {
+      query,
+      limit,
+      context,
+      syntax,
+      case: caseMode,
+      glob,
+    });
+    return normalizeResults(response.results ?? [], this.name);
+  }
+
+  async open({ path, line, context, offset, limit } = {}) {
+    const response = await this.#request("POST", "/open", { path, line, context, offset, limit });
+    return { ...response, source: this.name, readonly: true };
+  }
+
+  async #request(method, pathname, body = null) {
+    const headers = { accept: "application/json" };
+    if (body != null) headers["content-type"] = "application/json";
+    if (this.token) headers.authorization = `Bearer ${this.token}`;
+    const response = await this.fetchImpl(`${this.url}${pathname}`, {
+      method,
+      headers,
+      body: body == null ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        throw new Error(`remote memory ${this.name} returned non-JSON response`);
+      }
+    }
+    if (!response.ok) {
+      throw new Error(json?.error || `remote memory ${this.name} request failed: HTTP ${response.status}`);
+    }
+    return json ?? {};
+  }
+}
+
+export function createRemoteMemoryClients(sources = [], options = {}) {
+  return sources.map((source) => new RemoteMemoryClient({ ...source, ...options }));
+}
+
+function normalizeResults(results, source) {
+  return results.map((result) => ({
+    ...result,
+    source,
+    open: { source, path: result.path, line: result.line, context: result.open?.context ?? 40 },
+  }));
+}

package/src/memory/remote/config.mjs

@@ -0,0 +1,52 @@
+import { URL } from "node:url";
+
+export function normalizeRemoteMemorySources(config = {}) {
+  const sources = Array.isArray(config.remoteMemories) ? config.remoteMemories : [];
+  const normalized = [];
+  const seen = new Set();
+  for (const source of sources) {
+    const item = normalizeRemoteMemorySource(source);
+    if (!item || seen.has(item.name)) continue;
+    seen.add(item.name);
+    normalized.push(item);
+  }
+  return normalized;
+}
+
+export function normalizeRemoteMemorySource(source) {
+  if (!source || typeof source !== "object" || Array.isArray(source)) return null;
+  const name = normalizeSourceName(source.name);
+  const parsed = parseRemoteMemoryUrl(source.url ?? source.baseUrl, { token: source.token });
+  if (!name || !parsed.url) return null;
+  return { name, url: parsed.url, token: parsed.token ?? null };
+}
+
+export function parseRemoteMemoryUrl(rawUrl, { token = null } = {}) {
+  try {
+    const parsed = new URL(String(rawUrl ?? ""));
+    const urlToken = parsed.searchParams.get("token") || token || null;
+    parsed.searchParams.delete("token");
+    parsed.hash = "";
+    return { url: parsed.toString().replace(/\/$/, ""), token: urlToken };
+  } catch {
+    return { url: null, token: token || null };
+  }
+}
+
+export function normalizeSourceName(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+export function defaultRemoteMemoryName(url) {
+  try {
+    const parsed = new URL(url);
+    return normalizeSourceName(parsed.hostname || "remote-memory") || "remote-memory";
+  } catch {
+    return "remote-memory";
+  }
+}

package/src/memory/remote/server.mjs

@@ -0,0 +1,99 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { openMarkdownRoot, searchMarkdownRoot } from "../search.mjs";
+
+const MAX_BODY_BYTES = 64 * 1024;
+
+export function createRemoteMemoryServer({ root, name = "remote-memory", token = null } = {}) {
+  if (!root) throw new Error("remote memory server requires a folder");
+  const resolvedRoot = resolve(root);
+  const authToken = token || createMemoryServerToken();
+
+  const server = createServer(async (req, res) => {
+    try {
+      if (!isAuthorized(req, authToken)) return sendJson(res, 401, { error: "unauthorized" });
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (req.method === "GET" && url.pathname === "/metadata") {
+        return sendJson(res, 200, { name, rootLabel: resolvedRoot, capabilities: ["search", "open"], version: 1 });
+      }
+      if (req.method === "POST" && url.pathname === "/search") {
+        const body = await readJsonBody(req);
+        const results = searchMarkdownRoot({
+          root: resolvedRoot,
+          query: body.query ?? body.pattern,
+          limit: body.limit,
+          context: body.context,
+          syntax: body.syntax,
+          caseMode: body.case,
+          glob: body.glob,
+        });
+        return sendJson(res, 200, { results });
+      }
+      if (req.method === "POST" && url.pathname === "/open") {
+        const body = await readJsonBody(req);
+        const opened = openMarkdownRoot({
+          root: resolvedRoot,
+          path: body.path,
+          line: body.line,
+          context: body.context,
+          offset: body.offset,
+          limit: body.limit,
+        });
+        return sendJson(res, 200, {
+          path: opened.relativePath,
+          startLine: opened.startLine,
+          endLine: opened.endLine,
+          content: opened.content,
+          readonly: true,
+        });
+      }
+      return sendJson(res, 404, { error: "not found" });
+    } catch (err) {
+      return sendJson(res, 400, { error: err.message });
+    }
+  });
+
+  return { server, token: authToken, root: resolvedRoot, name };
+}
+
+export function createMemoryServerToken() {
+  return `mem_${randomBytes(18).toString("base64url")}`;
+}
+
+function isAuthorized(req, token) {
+  if (!token) return true;
+  const header = req.headers.authorization ?? "";
+  return header === `Bearer ${token}`;
+}
+
+function sendJson(res, statusCode, data) {
+  res.writeHead(statusCode, { "content-type": "application/json; charset=utf-8" });
+  res.end(`${JSON.stringify(data)}\n`);
+}
+
+function readJsonBody(req) {
+  return new Promise((resolveBody, reject) => {
+    let size = 0;
+    let body = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      size += Buffer.byteLength(chunk);
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error("request body too large"));
+        req.destroy();
+        return;
+      }
+      body += chunk;
+    });
+    req.on("error", reject);
+    req.on("end", () => {
+      if (!body.trim()) return resolveBody({});
+      try {
+        resolveBody(JSON.parse(body));
+      } catch {
+        reject(new Error("invalid JSON body"));
+      }
+    });
+  });
+}