@iamem/amem 0.1.1 → 0.1.3

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/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/publish.d.ts

@@ -1,5 +1,5 @@
 /** Paths that must be inside the published tarball for `npx @iamem/amem setup`. */
-export declare const REQUIRED_PACK_PATHS: readonly ["dist/cli.js", "dist/mcp.js", "dist/remember-contract.js", "ui-static/index.html", "ui-static/app.js", "ui-static/styles.css", "docs/remember-contract.md", "docs/agent-install-prompt.md", "docs/npm-release.md", "skills/amem-update-working-memory/SKILL.md", "scripts/mdm-offboard.sh"];
+export declare const REQUIRED_PACK_PATHS: readonly ["dist/cli.js", "dist/mcp.js", "dist/remember-contract.js", "ui-static/index.html", "ui-static/app.js", "ui-static/styles.css", "docs/remember-contract.md", "docs/agent-install-prompt.md", "docs/npm-release.md", "skills/amem-update-working-memory/SKILL.md", "scripts/mdm-offboard.sh", "scripts/postinstall.js"];
 export declare const PUBLISH_PACKAGE_NAME = "@iamem/amem";
 export type PublishReady = {
     root: string;

package/dist/publish.js

@@ -14,6 +14,7 @@ export const REQUIRED_PACK_PATHS = [
     "docs/npm-release.md",
     "skills/amem-update-working-memory/SKILL.md",
     "scripts/mdm-offboard.sh",
+    "scripts/postinstall.js",
 ];
 export const PUBLISH_PACKAGE_NAME = "@iamem/amem";
 export function packageRoot() {

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,
+    });
+}

package/dist/skills.d.ts

@@ -0,0 +1,106 @@
+export declare const SKILL_FILE = "SKILL.md";
+/** Subdirectories a skill may carry, matching the agentskills.io layout. */
+export declare const SKILL_ASSET_DIRS: string[];
+export type SkillSource = "local" | "bundled" | "import";
+export type SkillMeta = {
+    name: string;
+    description: string;
+    version: string | null;
+    tags: string[];
+    /** Absolute path to the skill's SKILL.md. */
+    path: string;
+    /** Absolute path to the skill directory. */
+    dir: string;
+    hash: string;
+    source: SkillSource;
+};
+export declare function skillsDir(): string;
+export declare function ensureSkillsDir(): string;
+export declare function hashSkillContent(content: string): string;
+/**
+ * Skill names become directory names and slash commands, so keep them to the identifier
+ * shape the ecosystem uses and never let one escape the skills directory.
+ */
+export declare function slugifySkillName(raw: string): string;
+export declare function isValidSkillName(raw: string): boolean;
+export type Frontmatter = {
+    meta: Record<string, string | string[]>;
+    body: string;
+};
+/**
+ * Minimal YAML-frontmatter reader — enough for the scalar and inline-list keys skills
+ * actually use. Nested keys are flattened to their leaf (`metadata.hermes.tags` -> `tags`)
+ * so a Hermes-authored skill and a Cursor-authored one both parse.
+ */
+export declare function parseFrontmatter(raw: string): Frontmatter;
+export declare function readSkillMeta(dir: string, source?: SkillSource): SkillMeta | null;
+/** Every skill on disk, sorted by name. Skips dot/underscore dirs like the hub state. */
+export declare function scanSkills(root?: string): SkillMeta[];
+export declare function findSkillOnDisk(name: string, root?: string): SkillMeta | null;
+export declare function skillDirFor(name: string, root?: string): string;
+export declare function readSkillBody(name: string, root?: string): string | null;
+/**
+ * Read a supporting file (`references/foo.md`). Skills come from other people, so the
+ * path is resolved and re-checked rather than trusted.
+ */
+export declare function readSkillAsset(name: string, relPath: string, root?: string): string | null;
+export declare function listSkillAssets(name: string, root?: string): string[];
+/** Render a SKILL.md from parts, for `amem skills new` and agent-authored saves. */
+export declare function renderSkillMarkdown(input: {
+    name: string;
+    description: string;
+    body?: string;
+    version?: string;
+    tags?: string[];
+}): string;
+export declare function writeSkill(name: string, content: string, root?: string): {
+    name: string;
+    path: string;
+    hash: string;
+};
+export declare function deleteSkill(name: string, root?: string): boolean;
+export type SkillScan = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Gate content before it lands in the library. Deny patterns come from policy so an IT
+ * operator's additions apply to skills too, not just claims.
+ */
+export declare function scanSkillContent(content: string, denyPatterns?: RegExp[]): SkillScan;
+/**
+ * Import a skill from a local directory. Local paths only — no registries and no network,
+ * which keeps this on the right side of the "no cloud, no hosted anything" line.
+ * Supporting files come along, but only from the allowlisted asset directories.
+ */
+export declare function importSkillFromPath(sourcePath: string, overrideName?: string, root?: string): {
+    name: string;
+    path: string;
+    files: string[];
+};
+export type IndexedSkill = SkillMeta & {
+    repoId: string | null;
+    uses: number;
+    lastUsedAt: string | null;
+    /** True when the file changed since it was installed — do not overwrite these. */
+    modified: boolean;
+};
+/**
+ * Reconcile the index with disk. Cheap enough to run before any read, which keeps the
+ * index honest when a user or agent edits a SKILL.md with ordinary file tools.
+ */
+export declare function syncSkillIndex(root?: string): IndexedSkill[];
+export declare function listIndexedSkills(root?: string): IndexedSkill[];
+export type RankedSkill = IndexedSkill & {
+    score: number;
+    reasons: string[];
+};
+/**
+ * Rank skills for a query. Deliberately matches on the index fields only — name,
+ * description, tags — because the whole point is to decide what is worth loading
+ * without paying for the bodies.
+ */
+export declare function skillSummary(s: SkillMeta | IndexedSkill): Record<string, unknown>;
+export declare function rankSkills(skills: IndexedSkill[], query: string, limit?: number): RankedSkill[];