@iamem/amem 0.1.2 → 0.2.0

package/dist/mcp.js

@@ -83,6 +83,122 @@ const TOOLS = [
             properties: { workspace: { type: "string" } },
         },
     },
+    {
+        name: "amem_skill_list",
+        description: "List stored skills (procedures the agent learned) as an index of names and descriptions only. Cheap — call this first, then amem_skill_view to load the one you need. Skills are longer procedures; use amem_context for small durable facts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Optional: rank the index against this task description",
+                },
+            },
+        },
+    },
+    {
+        name: "amem_skill_view",
+        description: "Load the full body of one skill by name, or a supporting file inside it. Call this only after amem_skill_list (or the 'Relevant skills' section of an amem context packet) shows a skill worth following.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Skill name from amem_skill_list" },
+                file: {
+                    type: "string",
+                    description: "Optional supporting file, e.g. references/api.md",
+                },
+                sessionId: {
+                    type: "string",
+                    description: "Optional conversation id, so amem can tell whether this procedure actually worked out",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "amem_skill_save",
+        description: "Save a non-trivial multi-step procedure you just worked out as a reusable skill. Use after solving something worth repeating — a workflow, a dead end you found the way past, or a correction the user gave you. Provide a full SKILL.md in `content`, or a description plus body.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Short slug, e.g. deploy-staging",
+                },
+                description: {
+                    type: "string",
+                    description: "One line on when to use this skill",
+                },
+                content: {
+                    type: "string",
+                    description: "Full SKILL.md, or the markdown body to wrap",
+                },
+                sessionId: {
+                    type: "string",
+                    description: "Optional conversation id, so amem can clear the nudge that prompted this",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "amem_task_list",
+        description: "List deferred agent tasks (Kanban) for a workspace/repo. Use for work to do later — not durable facts (use amem_remember for those). Default excludes done tasks.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspace: { type: "string" },
+                status: {
+                    type: "string",
+                    description: "backlog | next | doing | blocked | done",
+                },
+                include_done: { type: "boolean" },
+            },
+        },
+    },
+    {
+        name: "amem_task_add",
+        description: "Create a deferred agent task on the project Kanban (default backlog). Use for work that should not get lost in chat. Durable facts still go through amem_remember.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: { type: "string" },
+                body: { type: "string", description: "Why / notes" },
+                workspace: { type: "string" },
+                status: { type: "string", description: "backlog | next | doing | blocked | done" },
+                anchors: { type: "array", items: { type: "string" } },
+            },
+            required: ["title"],
+        },
+    },
+    {
+        name: "amem_task_update",
+        description: "Update a task title, notes, anchors, or move its Kanban status (backlog/next/doing/blocked/done).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                workspace: { type: "string" },
+                title: { type: "string" },
+                body: { type: "string" },
+                status: { type: "string" },
+                anchors: { type: "array", items: { type: "string" } },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "amem_task_complete",
+        description: "Mark a deferred agent task as done on the Kanban board.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                workspace: { type: "string" },
+            },
+            required: ["id"],
+        },
+    },
 ];
 function textResult(text, isError = false) {
     return {
@@ -127,6 +243,23 @@ function parseDays(value, fallback = 30) {
         return String(fallback);
     return String(Math.min(365, Math.floor(n)));
 }
+/**
+ * Keep the skill index at level 0. Returning bodies here would defeat the point of having
+ * a separate view call, so this hands back names and descriptions only.
+ */
+function compactSkillIndex(body, ranked) {
+    const source = (body ?? {});
+    const list = ranked ? (source.matches ?? []) : (source.skills ?? []);
+    return {
+        skills: list.map((s) => ({
+            name: s.name,
+            description: s.description,
+            tags: s.tags,
+            uses: s.uses,
+        })),
+        hint: "Call amem_skill_view with a name to load the full procedure.",
+    };
+}
 function compactGraph(body) {
     if (!body || typeof body !== "object")
         return body;
@@ -255,6 +388,94 @@ function callTool(name, args, fallbackWorkspace) {
         const result = api("GET", "/api/status", null, { workspace });
         return apiResult(result);
     }
+    if (name === "amem_skill_list") {
+        const query = {};
+        if (typeof args.query === "string" && args.query.trim())
+            query.q = args.query.trim();
+        const result = api("GET", "/api/skills", null, { query });
+        if (result.status >= 400)
+            return apiResult(result);
+        return jsonResult(compactSkillIndex(result.body, Boolean(query.q)));
+    }
+    if (name === "amem_skill_view") {
+        const skillName = typeof args.name === "string" ? args.name.trim() : "";
+        if (!skillName)
+            return textResult("name is required", true);
+        const query = { name: skillName };
+        if (typeof args.file === "string" && args.file.trim())
+            query.file = args.file.trim();
+        if (typeof args.sessionId === "string" && args.sessionId.trim()) {
+            query.session_id = args.sessionId.trim();
+        }
+        const result = api("GET", "/api/skills/view", null, { query });
+        if (result.status >= 400)
+            return apiResult(result);
+        const body = result.body;
+        // The body is markdown the agent should read as-is, not JSON to re-parse.
+        return textResult(typeof body?.content === "string" ? body.content : JSON.stringify(body));
+    }
+    if (name === "amem_skill_save") {
+        const skillName = typeof args.name === "string" ? args.name.trim() : "";
+        if (!skillName)
+            return textResult("name is required", true);
+        const result = api("POST", "/api/skills", {
+            name: skillName,
+            description: typeof args.description === "string" ? args.description : "",
+            content: typeof args.content === "string" ? args.content : "",
+            session_id: typeof args.sessionId === "string" ? args.sessionId : undefined,
+        }, { workspace });
+        return apiResult(result);
+    }
+    if (name === "amem_task_list") {
+        const query = {};
+        if (typeof args.status === "string" && args.status.trim())
+            query.status = args.status.trim();
+        if (args.include_done === true)
+            query.include_done = "1";
+        const result = api("GET", "/api/tasks", null, { workspace, query });
+        if (result.status >= 400)
+            return apiResult(result);
+        return jsonResult(result.body);
+    }
+    if (name === "amem_task_add") {
+        const title = typeof args.title === "string" ? args.title : "";
+        if (!title.trim())
+            return textResult("title is required", true);
+        const result = api("POST", "/api/tasks", {
+            title,
+            body: typeof args.body === "string" ? args.body : "",
+            status: typeof args.status === "string" ? args.status : "backlog",
+            anchors: args.anchors,
+            source: "mcp",
+        }, { workspace });
+        if (result.status >= 400)
+            return textResult(JSON.stringify(result.body), true);
+        return textResult(JSON.stringify(result.body));
+    }
+    if (name === "amem_task_update") {
+        const id = typeof args.id === "string" ? args.id : "";
+        if (!id.trim())
+            return textResult("id is required", true);
+        const result = api("PATCH", "/api/tasks", {
+            id,
+            title: typeof args.title === "string" ? args.title : undefined,
+            body: typeof args.body === "string" ? args.body : undefined,
+            status: typeof args.status === "string" ? args.status : undefined,
+            anchors: args.anchors,
+        }, { workspace });
+        if (result.status >= 400)
+            return textResult(JSON.stringify(result.body), true);
+        return textResult(JSON.stringify(result.body));
+    }
+    if (name === "amem_task_complete") {
+        const id = typeof args.id === "string" ? args.id : "";
+        if (!id.trim())
+            return textResult("id is required", true);
+        const result = api("POST", "/api/tasks/complete", { id }, { workspace });
+        if (result.status >= 400)
+            return textResult(JSON.stringify(result.body), true);
+        return textResult(JSON.stringify(result.body));
+    }
     return textResult(`Unknown tool: ${name}`, true);
 }
 function rpcResult(id, result) {

package/dist/platforms.js

@@ -2,6 +2,12 @@
 export const KNOWN_PLATFORMS = [
     { id: "cursor", label: "Cursor", hint: "Rules, skills, hooks", installs: "cursor" },
     { id: "claude", label: "Claude Code", hint: "Skills and settings hooks", installs: "claude" },
+    {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        hint: "MCP config installer",
+        installs: "host",
+    },
     { id: "copilot", label: "GitHub Copilot", hint: "MCP / HTTP API" },
     { id: "codex", label: "ChatGPT / Codex", hint: "MCP / HTTP API" },
     { id: "gemini", label: "Gemini", hint: "MCP / HTTP API" },

package/dist/policy.d.ts

@@ -8,6 +8,12 @@ export type AmemPolicy = {
     deny_claim_patterns: string[];
     /** Draft kinds that may auto-apply without Memory approve (still local). */
     auto_apply_kinds: string[];
+    /** Master switch for procedural memory (store, index, injection). */
+    skills_enabled: boolean;
+    /** Stage agent-authored skills for review instead of writing them straight to disk. */
+    skill_write_approval: boolean;
+    /** Let session-end suggest skills worth writing up. */
+    skill_capture: boolean;
 };
 export type PolicySource = {
     path: string;

package/dist/policy.js

@@ -22,6 +22,9 @@ export const DEFAULT_POLICY = {
     allowed_remote_hosts: [],
     deny_claim_patterns: [],
     auto_apply_kinds: [],
+    skills_enabled: true,
+    skill_write_approval: false,
+    skill_capture: true,
 };
 let cached = null;
 export function clearPolicyCache() {
@@ -60,6 +63,9 @@ export function parsePolicyToml(raw) {
             case "telemetry":
             case "ui_enabled":
             case "allow_export":
+            case "skills_enabled":
+            case "skill_write_approval":
+            case "skill_capture":
                 out[key] = parseBool(valueRaw, key, i + 1);
                 break;
             case "ui_bind":
@@ -131,6 +137,9 @@ function mergePolicy(base, overlay) {
         allowed_remote_hosts: overlay.allowed_remote_hosts ?? base.allowed_remote_hosts,
         deny_claim_patterns: overlay.deny_claim_patterns ?? base.deny_claim_patterns,
         auto_apply_kinds: overlay.auto_apply_kinds ?? base.auto_apply_kinds,
+        skills_enabled: overlay.skills_enabled ?? base.skills_enabled,
+        skill_write_approval: overlay.skill_write_approval ?? base.skill_write_approval,
+        skill_capture: overlay.skill_capture ?? base.skill_capture,
     };
 }
 /**
@@ -198,7 +207,13 @@ export function loadPolicy(forceReload = false) {
     // Clamp only the exfiltration-relevant knobs — blanking allowed_platforms here would
     // brick every host instead of protecting anything.
     if (sources.some((s) => s.error)) {
-        policy = { ...policy, allow_export: false, auto_apply_kinds: [] };
+        policy = {
+            ...policy,
+            allow_export: false,
+            auto_apply_kinds: [],
+            // Skills are instructions the agent follows, so an unreadable policy means review.
+            skill_write_approval: true,
+        };
     }
     cached = { policy, sources };
     return cached;

package/dist/remember-contract.js

@@ -64,11 +64,17 @@ Generic MCP host recipe. Same tools for every client — do not fork per product
 
 ## Connect
 
-Keep \`amem ui\` running, then attach:
+Two supported transports. Either is fine — pick one.
+
+**stdio (no daemon).** The host spawns amem itself. Let amem write the config:
+
+\`amem init --platform claude-desktop\`
+
+**HTTP (shared daemon).** Keep \`amem ui\` running, then attach:
 
 \`${MCP_URL_TEMPLATE}\`
 
-GUI hosts often cannot see Homebrew on PATH. Prefer the HTTP URL over a bare \`amem\` command.
+Whichever you pick, never configure a GUI host with a bare \`amem\` or \`node\` command. GUI apps are not launched from a login shell, so they inherit a minimal PATH with no Homebrew and no nvm: the connector registers but tool discovery never completes, and the host reports no reason. An absolute path — to the launcher or to the node binary — is what makes stdio work.
 
 ## Tools
 
@@ -88,8 +94,11 @@ ${ruleLines}
 function renderPaste() {
     return `amem remember contract v${REMEMBER_CONTRACT_VERSION}
 
-Connect (any MCP host): ${MCP_URL_TEMPLATE}
-Keep amem ui running. Do not use a bare amem command from GUI apps.
+Connect (any MCP host), either:
+- stdio, no daemon: amem init --platform claude-desktop (or point the host at an absolute launcher path)
+- HTTP, needs amem ui running: ${MCP_URL_TEMPLATE}
+
+Never give a GUI host a bare amem or node command — no login PATH, so tool discovery silently fails.
 
 Every task:
 1. amem_context — read local memory first (pass workspace=<slug>)

package/dist/repo-identity.d.ts

@@ -9,6 +9,16 @@ export declare function findGitRoot(startPath?: string): string | null;
 /** Normalize remotes so ssh/https clones of the same repo share a key. */
 export declare function normalizeRemoteUrl(url: string): string;
 export declare function detectRepoIdentity(cwd?: string): RepoIdentity;
+/**
+ * Why this directory must not become a repo binding, or null if it is fine.
+ *
+ * detectRepoIdentity falls back to the cwd when there is no git root, so
+ * running an init from a home directory would otherwise register the entire
+ * home as a "repo" — a binding that matches everything and can never be the
+ * right answer. Workspace roots under ~/.amem are created deliberately and are
+ * not affected: they are built by workspaceIdentity, not by cwd detection.
+ */
+export declare function unbindableRootReason(rootPath: string): string | null;
 export declare function slugifyWorkspace(name: string): string;
 export declare function workspaceIdentity(name: string, rootPath: string): RepoIdentity;
 export declare function parseWorkspaceSlug(remoteUrl: string | null | undefined): string | null;

package/dist/repo-identity.js

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { parse as parsePath, resolve } from "node:path";
 function runGit(cwd, args) {
     try {
         return execFileSync("git", args, {
@@ -51,6 +52,24 @@ export function detectRepoIdentity(cwd = process.cwd()) {
         defaultBranch,
     };
 }
+/**
+ * Why this directory must not become a repo binding, or null if it is fine.
+ *
+ * detectRepoIdentity falls back to the cwd when there is no git root, so
+ * running an init from a home directory would otherwise register the entire
+ * home as a "repo" — a binding that matches everything and can never be the
+ * right answer. Workspace roots under ~/.amem are created deliberately and are
+ * not affected: they are built by workspaceIdentity, not by cwd detection.
+ */
+export function unbindableRootReason(rootPath) {
+    const resolved = resolve(rootPath);
+    const parsed = parsePath(resolved);
+    if (resolved === parsed.root)
+        return "the filesystem root";
+    if (resolved === resolve(homedir()))
+        return "your home directory";
+    return null;
+}
 export function slugifyWorkspace(name) {
     const slug = name
         .trim()

package/dist/skill-capture.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Deciding when a session is worth writing up as a skill.
+ *
+ * This is tuned for precision, not recall. Memory drafts already taught us that a noisy
+ * queue is worse than an empty one — a user facing hundreds of suggestions stops reading
+ * all of them. A session must show several independent signals before it earns one
+ * suggestion, and a session can never produce more than one.
+ */
+import { type RepoRow, type SkillDraftRow } from "./db.js";
+export type SessionNote = {
+    role: string;
+    text: string;
+};
+export type SkillOpportunity = {
+    title: string;
+    summary: string;
+    reasons: string[];
+    score: number;
+};
+/**
+ * Score a session against the three triggers Hermes names: a multi-step workflow worth
+ * repeating, a dead end the agent found the way past, and a correction from the user.
+ * Requires at least two distinct signals plus real procedural content.
+ */
+export declare function detectSkillOpportunity(notes: SessionNote[]): SkillOpportunity | null;
+/**
+ * Queue at most one suggestion per session. The agent, not amem, writes the actual
+ * SKILL.md — amem has no model, so it only points at the material.
+ */
+export declare function captureSkillSuggestion(input: {
+    repo: RepoRow;
+    sessionId?: string | null;
+    notes: SessionNote[];
+}): SkillDraftRow | null;
+/**
+ * A skill was followed this session and things still went wrong — that is the signal the
+ * skill itself needs work. Mirrors the existing miss→learn loop, pointed at procedures.
+ */
+export declare function captureSkillRevision(input: {
+    repo: RepoRow;
+    sessionId?: string | null;
+    notes: SessionNote[];
+}): SkillDraftRow | null;

package/dist/skill-capture.js

@@ -0,0 +1,146 @@
+/**
+ * Deciding when a session is worth writing up as a skill.
+ *
+ * This is tuned for precision, not recall. Memory drafts already taught us that a noisy
+ * queue is worse than an empty one — a user facing hundreds of suggestions stops reading
+ * all of them. A session must show several independent signals before it earns one
+ * suggestion, and a session can never produce more than one.
+ */
+import { insertSkillDraft, listRecentSkillUses, listSkillsUsedInSession, skillDraftExists, } from "./db.js";
+import { loadPolicy } from "./policy.js";
+/** Numbered or bulleted command-ish steps — the shape of a procedure. */
+const STEP_RE = /^\s*(?:\d+[.)]\s+|[-*]\s+)/gm;
+const COMMAND_RE = /\b(?:npm|pnpm|yarn|npx|git|docker|kubectl|make|cargo|go|python3?|node|psql|aws|terraform|ssh|curl)\s+[\w-]/g;
+const ERROR_RE = /\b(?:error|failed|failure|exception|traceback|not found|cannot find|denied|timed? out|broken|does ?n[o']t work)\b/i;
+const RESOLUTION_RE = /\b(?:fixed|resolved|works now|that did it|success(?:ful)?|passing|green|it works|solved|now working)\b/i;
+const CORRECTION_RE = /\b(?:no,|nope|actually|that'?s wrong|not quite|instead of|don'?t do that|wrong approach|try again)\b/i;
+function assistantText(notes) {
+    return notes
+        .filter((n) => n.role === "assistant")
+        .map((n) => n.text)
+        .join("\n\n");
+}
+function userText(notes) {
+    return notes
+        .filter((n) => n.role === "user")
+        .map((n) => n.text)
+        .join("\n\n");
+}
+function countMatches(text, re) {
+    return (text.match(re) ?? []).length;
+}
+/**
+ * Score a session against the three triggers Hermes names: a multi-step workflow worth
+ * repeating, a dead end the agent found the way past, and a correction from the user.
+ * Requires at least two distinct signals plus real procedural content.
+ */
+export function detectSkillOpportunity(notes) {
+    if (!Array.isArray(notes) || notes.length < 4)
+        return null;
+    const assistant = assistantText(notes);
+    const user = userText(notes);
+    if (assistant.trim().length < 400)
+        return null;
+    const reasons = [];
+    let score = 0;
+    const steps = countMatches(assistant, STEP_RE);
+    const commands = countMatches(assistant, COMMAND_RE);
+    // A procedure needs enumerated steps or repeated concrete commands, not just prose.
+    if (steps >= 3) {
+        score += 30;
+        reasons.push(`${steps} enumerated steps`);
+    }
+    if (commands >= 3) {
+        score += 20;
+        reasons.push(`${commands} shell commands`);
+    }
+    if (steps < 3 && commands < 3)
+        return null;
+    const hitError = ERROR_RE.test(assistant);
+    if (hitError && RESOLUTION_RE.test(assistant)) {
+        score += 25;
+        reasons.push("hit an error and found the working path");
+    }
+    if (CORRECTION_RE.test(user)) {
+        score += 20;
+        reasons.push("user corrected the approach");
+    }
+    const turns = notes.filter((n) => n.role === "user").length;
+    if (turns >= 3) {
+        score += 10;
+        reasons.push(`${turns} back-and-forth turns`);
+    }
+    // Two independent signals minimum: one lone heuristic is not evidence of a procedure.
+    if (reasons.length < 2 || score < 55)
+        return null;
+    const firstUser = notes.find((n) => n.role === "user")?.text ?? "";
+    const title = firstUser.replace(/\s+/g, " ").trim().slice(0, 96) || "Multi-step workflow";
+    return {
+        title,
+        summary: firstUser.replace(/\s+/g, " ").trim().slice(0, 400),
+        reasons,
+        score,
+    };
+}
+/**
+ * Queue at most one suggestion per session. The agent, not amem, writes the actual
+ * SKILL.md — amem has no model, so it only points at the material.
+ */
+export function captureSkillSuggestion(input) {
+    if (!loadPolicy().policy.skill_capture)
+        return null;
+    const sid = input.sessionId || "unknown";
+    const source = `skill-suggest:${sid}`;
+    if (skillDraftExists(source))
+        return null;
+    const opportunity = detectSkillOpportunity(input.notes);
+    if (!opportunity)
+        return null;
+    return insertSkillDraft({
+        repoId: input.repo.id,
+        title: opportunity.title,
+        summary: opportunity.summary,
+        kind: "suggestion",
+        source,
+        sessionId: input.sessionId,
+        reasons: opportunity.reasons,
+    });
+}
+/**
+ * A skill was followed this session and things still went wrong — that is the signal the
+ * skill itself needs work. Mirrors the existing miss→learn loop, pointed at procedures.
+ */
+export function captureSkillRevision(input) {
+    if (!loadPolicy().policy.skill_capture)
+        return null;
+    const sid = input.sessionId || "";
+    // Prefer the exact session; fall back to recent use in this memory, because MCP
+    // clients do not reliably pass a session id through to skill views.
+    const used = sid ? listSkillsUsedInSession(sid, 3) : [];
+    const candidates = used.length > 0 ? used : listRecentSkillUses(input.repo.id, 120, 3);
+    if (candidates.length === 0)
+        return null;
+    const assistant = assistantText(input.notes);
+    const user = userText(input.notes);
+    const struggled = (ERROR_RE.test(assistant) && RESOLUTION_RE.test(assistant)) || CORRECTION_RE.test(user);
+    if (!struggled)
+        return null;
+    const target = candidates[0];
+    const source = `skill-revise:${sid || input.repo.id}:${target}`;
+    if (skillDraftExists(source))
+        return null;
+    const reasons = [
+        `followed ${target} but still hit trouble`,
+        CORRECTION_RE.test(user) ? "user corrected the approach" : "error then recovery in the session",
+    ];
+    return insertSkillDraft({
+        repoId: input.repo.id,
+        title: `Revise ${target}`,
+        summary: `The ${target} skill was loaded this session but the work still went sideways. Check whether the procedure is missing a step or a pitfall.`,
+        kind: "revision",
+        targetSkill: target,
+        source,
+        sessionId: input.sessionId,
+        reasons,
+    });
+}