loopctl-mcp-server 2.36.0 → 2.38.0

package/README.md

@@ -121,7 +121,7 @@ REST endpoint (`PATCH /api/v1/tenants/me/llm-config`), and the docs — so you (
 autonomous agent) can self-remediate without a human. Full agent-tenant lifecycle:
 [`docs/onboarding-agent-tenant.md`](../docs/onboarding-agent-tenant.md).
 
-## Tools (73)
+## Tools (83)
 
 ### Project Tools
 
@@ -217,6 +217,24 @@ autonomous agent) can self-remediate without a human. Full agent-tenant lifecycl
 | `knowledge_okf_export` | **Requires `LOOPCTL_USER_KEY`.** Export the wiki as a portable OKF (Open Knowledge Format) v0.1 bundle of markdown files. Writes to `out_dir`, or returns `{files, meta}` inline. |
 | `knowledge_okf_import` | **Requires `LOOPCTL_USER_KEY`.** Import an OKF v0.1 bundle from a local directory. Creates or (with `merge`) updates articles; tolerates and preserves unknown frontmatter. |
 
+### Agent Memory Tools (agent key)
+
+`memory_*` is YOUR OWN scoped, private, accumulated working state — running notes, in-flight
+task context, recall across sessions — NOT the shared knowledge wiki. Use `memory_*` for that
+private per-scope state; use `knowledge_*` for curated knowledge other agents should see. Scope
+(`tenant_id`/`subject_id`) is resolved server-side from your API key — none of these tools accept
+a `tenant_id`/`subject_id`, so there is no NON-SUPERADMIN way to read or write into another
+scope. (The one carve-out: `memory_list`'s `all_subjects` boolean IS a cross-subject read, but
+it is enforced server-side and a no-op for a non-superadmin key — see below.)
+
+| Tool | Description |
+|---|---|
+| `memory_remember` | Write to your own working memory. `tier` selects the substrate: `long_term` (default; requires `text`, embedded asynchronously and later recalled by semantic similarity via `memory_recall`) or `session` (short-term; requires `session_id`, `content`, `expires_at` — pruned after expiry, not semantically recalled). Returns 201 with the stored memory. Optional: `confidence`, `tags`, `source_session_id`, `metadata` (long-term); `role` (session). |
+| `memory_recall` | Semantically recall your own long-term memories most similar to `query`. When embedding generation is unavailable the response degrades to a recent-first text match with `meta.fallback: true` and a stable `meta.reason` (score is `null` on that path) — check `meta.fallback` before treating a short/empty result as a genuinely empty scope. `meta.total_count`/`meta.underfilled` are also returned. Optional: `limit`, `include_superseded`. |
+| `memory_list` | List your own long-term memories, newest first, paginated with `meta.total_count/limit/offset` (the true scoped count, never silently capped by `limit`). Optional: `limit`, `offset`, `include_superseded`, `all_subjects` (superadmin only; ignored for non-superadmin keys). |
+| `memory_forget` | Delete one of your own long-term memories by id. A foreign-subject, foreign-tenant, or unknown id returns 404 (no existence leak). Required: `id`. |
+| `memory_promote` | Call at session end to compile this session's short-term (`session`-tier) memory into durable `long_term` memory — unlike `memory_remember` (a single explicit write), this compiles the whole session in one shot; fire it once at session end, not per turn. Returns 202 with `{job_id, session_id, status: "enqueued"}` — promotion runs asynchronously, so the resulting memory is recallable via `memory_recall` only after the worker drains. You can only promote your own sessions (scope resolved server-side from your key). Required: `session_id`. |
+
 ### Knowledge Management Tools (orchestrator key)
 
 | Tool | Description |

package/index.js

@@ -18,6 +18,7 @@ import {
   projectsPath,
   ingestionJobsPath,
   llmUsagePath,
+  memoryPath,
   parseJsonResponseBody,
 } from "./lib/http-helpers.js";
 import {
@@ -1064,6 +1065,111 @@ async function knowledgeCreate({
   return toContent(result);
 }
 
+// --- Agent Memory Tools (US-28.4) ---
+//
+// memory_* is YOUR own scoped, private, accumulated working state — recall
+// across sessions, running notes, in-flight task context. knowledge_* is the
+// curated, shared wiki. Scope (tenant_id/subject_id) is resolved SERVER-SIDE
+// from the API key (US-28.3) — these tools never accept or forward a
+// tenant_id/subject_id, so there is no NON-SUPERADMIN way to express a
+// cross-scope read/write here even by mistake. (The one carve-out:
+// memory_list's `all_subjects` boolean IS a cross-subject read, but it is
+// enforced server-side and a no-op for a non-superadmin key — see its
+// description below.) Routes through the shared apiCall/witness client
+// (same as every other write tool), so witness/STH persistence + the
+// transparent 412 self-heal on a fresh MCP process apply automatically
+// (AC-28.4.3) — no bespoke witness code needed.
+
+async function memoryRemember({
+  tier,
+  text,
+  confidence,
+  tags,
+  source_session_id,
+  session_id,
+  role,
+  content,
+  expires_at,
+  metadata,
+}) {
+  const payload = {};
+  if (tier) payload.tier = tier;
+  if (text != null) payload.text = text;
+  if (confidence != null) payload.confidence = confidence;
+  if (tags) payload.tags = tags;
+  if (source_session_id) payload.source_session_id = source_session_id;
+  if (session_id) payload.session_id = session_id;
+  if (role) payload.role = role;
+  if (content != null) payload.content = content;
+  if (expires_at) payload.expires_at = expires_at;
+  if (metadata != null) payload.metadata = metadata;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function memoryRecall({ query, limit, include_superseded }) {
+  const payload = { query };
+  if (limit != null) payload.limit = limit;
+  if (include_superseded != null) payload.include_superseded = include_superseded;
+
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory/recall",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  // Surface meta (fallback/reason/total_count/underfilled) so the caller can tell
+  // a degraded recall from a genuinely empty scope (AC-28.4.4) — toContent already
+  // preserves the full result (data + meta), we just keep this call explicit.
+  return toContent(result);
+}
+
+async function memoryList({ limit, offset, include_superseded, all_subjects }) {
+  // all_subjects is superadmin-only server-side; a non-superadmin key sending
+  // this is ignored (falls back to its own subject) rather than erroring — the
+  // one deliberate cross-subject read this MCP surface can express (module
+  // comment above), and only for a superadmin caller.
+  const path = memoryPath({ limit, offset, include_superseded, all_subjects });
+  const result = await apiCall("GET", path, null, process.env.LOOPCTL_AGENT_KEY);
+  // Surface meta.total_count/limit/offset (AC-28.4.4).
+  return toContent(result);
+}
+
+async function memoryForget({ id }) {
+  // Path-injection guard (mirrors knowledgeAgentUsage's UUID_RE check below).
+  if (typeof id !== "string" || !UUID_RE.test(id)) {
+    return {
+      content: [{ type: "text", text: "Error: id must be a canonical UUID (8-4-4-4-12 hex)." }],
+      isError: true,
+    };
+  }
+
+  const result = await apiCall(
+    "DELETE",
+    `/api/v1/memory/${id}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function memoryPromote({ session_id }) {
+  const payload = { session_id };
+  const result = await apiCall(
+    "POST",
+    "/api/v1/memory/promote",
+    payload,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 // --- Knowledge Management Tools (orch key) ---
 
 async function knowledgePublish({ article_id }) {
@@ -3052,6 +3158,181 @@ const TOOLS = [
     },
   },
 
+  // Agent Memory Tools (US-28.4)
+  {
+    name: "memory_remember",
+    description:
+      "Write to YOUR OWN scoped, private, accumulated working memory — running notes, " +
+      "in-flight task state, decisions you made this session — NOT the shared knowledge " +
+      "wiki. Use memory_* for private per-scope working state across sessions; use " +
+      "knowledge_* for curated, shared knowledge articles other agents should see. Scope " +
+      "(tenant_id/subject_id) is resolved server-side from your API key — never pass or " +
+      "expect a tenant_id/subject_id here; there is no way to write into another scope. " +
+      "`tier` selects the substrate: `long_term` (default; requires `text`, embedded " +
+      "asynchronously and later recalled by semantic similarity via memory_recall) or " +
+      "`session` (short-term; requires `session_id`, `content`, `expires_at` — pruned " +
+      "after expiry, not semantically recalled). Returns 201 with the stored memory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tier: {
+          type: "string",
+          enum: ["long_term", "session"],
+          description: "Memory substrate. Defaults to long_term.",
+        },
+        text: {
+          type: "string",
+          description: "Long-term memory content (required when tier=long_term).",
+        },
+        confidence: {
+          type: "number",
+          description: "Optional: confidence score (0.0-1.0) for a long-term memory.",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional: tags for a long-term memory.",
+        },
+        source_session_id: {
+          type: "string",
+          description: "Optional: the session this long-term memory was distilled from.",
+        },
+        session_id: {
+          type: "string",
+          description: "Session identifier (required when tier=session).",
+        },
+        role: {
+          type: "string",
+          enum: ["user", "assistant", "system", "fact"],
+          description: "Optional: speaker role for a session-tier turn.",
+        },
+        content: {
+          type: "string",
+          description: "Session turn content (required when tier=session).",
+        },
+        expires_at: {
+          type: "string",
+          format: "date-time",
+          description: "Prune deadline (required when tier=session).",
+        },
+        metadata: {
+          type: "object",
+          description: "Optional: arbitrary structured metadata to attach to the memory.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "memory_recall",
+    description:
+      "Semantically recall YOUR OWN long-term memories most similar to `query` — private, " +
+      "scoped working state, NOT the shared knowledge wiki. Use memory_* for your scoped, " +
+      "private, accumulated working state across sessions; use knowledge_* for curated, " +
+      "shared knowledge articles. Scope is resolved server-side from your API key. When " +
+      "embedding generation is unavailable the response degrades to a recent-first text " +
+      "match with `meta.fallback: true` and a stable `meta.reason` (score is null on that " +
+      "path) — check meta.fallback before treating a short/empty result as a genuinely " +
+      "empty scope. `meta.total_count` and `meta.underfilled` are also returned so you can " +
+      "distinguish a short page from a hard cap.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Text to embed / match against.",
+        },
+        limit: {
+          type: "integer",
+          description: "Optional: max results, clamped to the vector-search max (no silent hard cap).",
+        },
+        include_superseded: {
+          type: "boolean",
+          description: "Optional: include superseded memories (default false).",
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory_list",
+    description:
+      "List YOUR OWN long-term memories, newest first — private, scoped working state, " +
+      "NOT the shared knowledge wiki. Use memory_* for your scoped, private, accumulated " +
+      "working state across sessions; use knowledge_* for curated, shared knowledge " +
+      "articles. Scope is resolved server-side from your API key. Paginated with " +
+      "`meta.total_count/limit/offset` (the true scoped count, never silently capped by " +
+      "limit) so you can distinguish an empty scope from a short page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "integer",
+          description: "Optional: page size (default 50, max 200).",
+        },
+        offset: {
+          type: "integer",
+          description: "Optional: records to skip (default 0).",
+        },
+        include_superseded: {
+          type: "boolean",
+          description: "Optional: include superseded memories (default false).",
+        },
+        all_subjects: {
+          type: "boolean",
+          description:
+            "Optional, superadmin only: list all subjects' memories in the tenant. Ignored " +
+            "(falls back to your own subject) for non-superadmin keys.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "memory_forget",
+    description:
+      "Delete one of YOUR OWN long-term memories by id — private, scoped working state, " +
+      "NOT the shared knowledge wiki. Use memory_* for your scoped, private, accumulated " +
+      "working state; use knowledge_* for curated, shared knowledge articles (delete those " +
+      "with knowledge_delete). Scope is resolved server-side from your API key: a foreign-" +
+      "subject, foreign-tenant, or unknown id returns 404 (no existence leak) rather than " +
+      "revealing whether it exists in another scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          format: "uuid",
+          description: "The UUID of the memory to forget.",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "memory_promote",
+    description:
+      "Call at session end to compile this session's short-term memory into durable long-term memory" +
+      " — private, scoped working state, NOT the shared knowledge wiki. Unlike " +
+      "memory_remember, which writes a single explicit fact, this compiles the WHOLE session's " +
+      "session-tier memory in one shot — fire it once at session end, not per turn. Scope " +
+      "(tenant_id/subject_id) is resolved server-side from your API key: you can only promote " +
+      "your OWN sessions. Returns 202 Accepted with `{job_id, session_id, status: \"enqueued\"}` " +
+      "— promotion runs asynchronously via a background worker, so the resulting long-term " +
+      "memory becomes recallable via memory_recall only after that worker drains, not " +
+      "immediately.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: {
+          type: "string",
+          description: "The session whose short-term memory to compile into long-term memory.",
+        },
+      },
+      required: ["session_id"],
+    },
+  },
+
   // Knowledge Management Tools (orchestrator key)
   {
     name: "knowledge_publish",
@@ -4263,6 +4544,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "knowledge_create":
       return await knowledgeCreate(args);
 
+    // Agent Memory Tools
+    case "memory_remember":
+      return await memoryRemember(args);
+
+    case "memory_recall":
+      return await memoryRecall(args);
+
+    case "memory_list":
+      return await memoryList(args);
+
+    case "memory_forget":
+      return await memoryForget(args);
+
+    case "memory_promote":
+      return await memoryPromote(args);
+
     // Knowledge Management Tools
     case "knowledge_publish":
       return await knowledgePublish(args);

package/lib/http-helpers.js

@@ -68,6 +68,24 @@ export function llmUsagePath({ from, to, limit, offset } = {}) {
   ])}`;
 }
 
+/**
+ * Path for `memory_list`, honoring limit/offset/include_superseded/all_subjects
+ * (US-28.4). Routes through the shared `buildQuery` helper (rather than a local
+ * `URLSearchParams` mirror) so the query-string construction is exercised by the
+ * SAME code the server ships.
+ *
+ * @param {{ limit?: number, offset?: number, include_superseded?: boolean, all_subjects?: boolean }} [args]
+ * @returns {string}
+ */
+export function memoryPath({ limit, offset, include_superseded, all_subjects } = {}) {
+  return `/api/v1/memory${buildQuery([
+    ["limit", limit],
+    ["offset", offset],
+    ["include_superseded", include_superseded],
+    ["all_subjects", all_subjects],
+  ])}`;
+}
+
 /**
  * Defensively parse the raw text body of a JSON-content-type HTTP response
  * (#249, mcp-03).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.36.0",
+  "version": "2.38.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",