@iamem/amem 0.1.2 → 0.2.0

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[];

package/dist/skills.js

@@ -0,0 +1,422 @@
+/**
+ * Procedural memory. Claims are small facts that ride in every packet; a skill is a
+ * longer procedure that should only load when it is relevant.
+ *
+ * Files on disk are the source of truth (`~/.amem/skills/<name>/SKILL.md`), because every
+ * other agent tool in this ecosystem — Cursor, Claude, Hermes — discovers skills by
+ * scanning folders, and a skill's `references/` and `scripts/` do not fit in a column.
+ * SQLite only indexes them for ranking and usage stats; see `src/db.ts`.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { pruneSkillRows, upsertSkillRow } from "./db.js";
+import { amemHome } from "./paths.js";
+import { compiledDenyPatterns } from "./policy.js";
+import { tokenize } from "./search.js";
+export const SKILL_FILE = "SKILL.md";
+/** Subdirectories a skill may carry, matching the agentskills.io layout. */
+export const SKILL_ASSET_DIRS = ["references", "templates", "scripts", "examples", "assets"];
+export function skillsDir() {
+    return join(amemHome(), "skills");
+}
+export function ensureSkillsDir() {
+    const dir = skillsDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+export function hashSkillContent(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex").slice(0, 16);
+}
+/**
+ * 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 function slugifySkillName(raw) {
+    const slug = String(raw || "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return slug;
+}
+export function isValidSkillName(raw) {
+    return /^[a-z][a-z0-9_-]*$/.test(String(raw || "")) && String(raw).length <= 64;
+}
+/**
+ * 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 function parseFrontmatter(raw) {
+    const text = String(raw ?? "").replace(/^\uFEFF/, "");
+    const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+    if (!match)
+        return { meta: {}, body: text.trim() };
+    const meta = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        if (!line.trim() || line.trim().startsWith("#"))
+            continue;
+        const kv = /^\s*([A-Za-z0-9_.-]+)\s*:\s*(.*)$/.exec(line);
+        if (!kv)
+            continue;
+        const key = kv[1].split(".").pop().toLowerCase();
+        const value = kv[2].trim();
+        if (!value)
+            continue; // a bare `metadata:` parent carries nothing itself
+        if (value.startsWith("[") && value.endsWith("]")) {
+            meta[key] = value
+                .slice(1, -1)
+                .split(",")
+                .map((v) => stripQuotes(v.trim()))
+                .filter(Boolean);
+        }
+        else {
+            meta[key] = stripQuotes(value);
+        }
+    }
+    return { meta, body: text.slice(match[0].length).trim() };
+}
+function stripQuotes(value) {
+    const v = value.trim();
+    if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
+        return v.slice(1, -1);
+    }
+    return v;
+}
+function metaString(meta, key) {
+    const v = meta[key];
+    if (typeof v === "string" && v.trim())
+        return v.trim();
+    return null;
+}
+function metaList(meta, key) {
+    const v = meta[key];
+    if (Array.isArray(v))
+        return v.filter((s) => typeof s === "string" && s.trim()).map((s) => s.trim());
+    if (typeof v === "string" && v.trim())
+        return v.split(/[,\s]+/).filter(Boolean);
+    return [];
+}
+/** First markdown heading, used when a skill has no `description:` to show. */
+function firstHeading(body) {
+    for (const line of body.split(/\r?\n/)) {
+        const h = /^#{1,3}\s+(.+?)\s*$/.exec(line);
+        if (h)
+            return h[1].trim();
+    }
+    return "";
+}
+export function readSkillMeta(dir, source = "local") {
+    const file = join(dir, SKILL_FILE);
+    if (!existsSync(file) || !statSync(file).isFile())
+        return null;
+    const raw = readFileSync(file, "utf8");
+    const { meta, body } = parseFrontmatter(raw);
+    // Name resolution mirrors the ecosystem: frontmatter first, then the folder name.
+    const declared = metaString(meta, "name");
+    const name = isValidSkillName(declared || "") ? declared : slugifySkillName(dir.split(sep).pop() || "");
+    if (!name)
+        return null;
+    return {
+        name,
+        description: metaString(meta, "description") || firstHeading(body),
+        version: metaString(meta, "version"),
+        tags: metaList(meta, "tags"),
+        path: file,
+        dir,
+        hash: hashSkillContent(raw),
+        source,
+    };
+}
+/** Every skill on disk, sorted by name. Skips dot/underscore dirs like the hub state. */
+export function scanSkills(root = skillsDir()) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith(".") || entry.name.startsWith("_"))
+            continue;
+        const dir = join(root, entry.name);
+        const meta = readSkillMeta(dir);
+        if (meta) {
+            out.push(meta);
+            continue;
+        }
+        // One level of category nesting, the way Hermes groups skills (mlops/axolotl).
+        for (const child of readdirSync(dir, { withFileTypes: true })) {
+            if (!child.isDirectory() || child.name.startsWith("."))
+                continue;
+            const nested = readSkillMeta(join(dir, child.name));
+            if (nested)
+                out.push(nested);
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function findSkillOnDisk(name, root = skillsDir()) {
+    const slug = slugifySkillName(name);
+    if (!slug)
+        return null;
+    return scanSkills(root).find((s) => s.name === slug) ?? null;
+}
+export function skillDirFor(name, root = skillsDir()) {
+    const slug = slugifySkillName(name);
+    if (!isValidSkillName(slug))
+        throw new Error(`Invalid skill name: ${name}`);
+    return join(root, slug);
+}
+export function readSkillBody(name, root = skillsDir()) {
+    const meta = findSkillOnDisk(name, root);
+    return meta ? readFileSync(meta.path, "utf8") : 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 function readSkillAsset(name, relPath, root = skillsDir()) {
+    const meta = findSkillOnDisk(name, root);
+    if (!meta)
+        return null;
+    const base = resolve(meta.dir);
+    const target = resolve(base, relPath);
+    // resolve() collapses "..", and an absolute relPath lands outside base — both caught here.
+    if (target !== base && !target.startsWith(base + sep))
+        return null;
+    if (!existsSync(target) || !statSync(target).isFile())
+        return null;
+    return readFileSync(target, "utf8");
+}
+export function listSkillAssets(name, root = skillsDir()) {
+    const meta = findSkillOnDisk(name, root);
+    if (!meta)
+        return [];
+    const out = [];
+    for (const sub of SKILL_ASSET_DIRS) {
+        const dir = join(meta.dir, sub);
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isFile())
+                out.push(`${sub}/${entry.name}`);
+        }
+    }
+    return out.sort();
+}
+/** Render a SKILL.md from parts, for `amem skills new` and agent-authored saves. */
+export function renderSkillMarkdown(input) {
+    const lines = ["---", `name: ${input.name}`, `description: ${input.description}`];
+    if (input.version)
+        lines.push(`version: ${input.version}`);
+    if (input.tags?.length)
+        lines.push(`tags: [${input.tags.join(", ")}]`);
+    lines.push("---", "");
+    const body = (input.body || "").trim();
+    lines.push(body || defaultSkillBody(input.name));
+    return `${lines.join("\n")}\n`;
+}
+function defaultSkillBody(name) {
+    const title = name.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+    return [
+        `# ${title}`,
+        "",
+        "## When to use",
+        "",
+        "Describe the trigger — the situation where this procedure applies.",
+        "",
+        "## Procedure",
+        "",
+        "1. First step.",
+        "2. Second step.",
+        "",
+        "## Pitfalls",
+        "",
+        "- Known failure modes and how to get past them.",
+        "",
+        "## Verification",
+        "",
+        "How to confirm it worked.",
+    ].join("\n");
+}
+export function writeSkill(name, content, root = skillsDir()) {
+    const slug = slugifySkillName(name);
+    if (!isValidSkillName(slug))
+        throw new Error(`Invalid skill name: ${name}`);
+    const dir = join(root, slug);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, SKILL_FILE);
+    const body = content.endsWith("\n") ? content : `${content}\n`;
+    writeFileSync(path, body, { mode: 0o600 });
+    return { name: slug, path, hash: hashSkillContent(body) };
+}
+export function deleteSkill(name, root = skillsDir()) {
+    const meta = findSkillOnDisk(name, root);
+    if (!meta)
+        return false;
+    rmSync(meta.dir, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Prompt-injection shapes that have no business in a stored procedure. A skill is riskier
+ * than a claim: a claim is a fact the agent reads, a skill is an instruction it follows.
+ */
+const SKILL_INJECTION_PATTERNS = [
+    {
+        re: /ignore\s+(?:all\s+)?(?:previous|prior|above)\s+instructions/i,
+        reason: "prompt-injection directive",
+    },
+    { re: /disregard\s+(?:your\s+)?(?:system\s+prompt|safety|guidelines)/i, reason: "safety override" },
+    { re: /\bcurl\b[^\n]*\|\s*(?:ba)?sh\b/i, reason: "pipes a remote script into a shell" },
+    { re: /rm\s+-rf\s+[~/]\s*(?:$|[^\w/])/im, reason: "destructive filesystem command" },
+    {
+        re: /(?:curl|wget|fetch)[^\n]*(?:AWS_|API_KEY|SECRET|TOKEN|\.env\b|id_rsa)/i,
+        reason: "looks like credential exfiltration",
+    },
+];
+/**
+ * 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 function scanSkillContent(content, denyPatterns) {
+    const text = String(content ?? "");
+    if (!text.trim())
+        return { ok: false, reason: "empty skill content" };
+    for (const { re, reason } of SKILL_INJECTION_PATTERNS) {
+        if (re.test(text))
+            return { ok: false, reason };
+    }
+    const deny = denyPatterns ?? compiledDenyPatterns();
+    for (const re of deny) {
+        if (re.test(text))
+            return { ok: false, reason: `matches deny pattern ${re.source}` };
+    }
+    return { ok: true };
+}
+/**
+ * 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 function importSkillFromPath(sourcePath, overrideName, root = skillsDir()) {
+    const src = resolve(sourcePath);
+    if (!existsSync(src))
+        throw new Error(`No such path: ${sourcePath}`);
+    const srcDir = statSync(src).isDirectory() ? src : join(src, "..");
+    const skillFile = statSync(src).isDirectory() ? join(src, SKILL_FILE) : src;
+    if (!existsSync(skillFile))
+        throw new Error(`No ${SKILL_FILE} found at ${sourcePath}`);
+    const raw = readFileSync(skillFile, "utf8");
+    const scan = scanSkillContent(raw);
+    if (!scan.ok)
+        throw new Error(`Refusing to import: ${scan.reason}`);
+    const { meta } = parseFrontmatter(raw);
+    const declared = typeof meta.name === "string" ? meta.name : "";
+    const candidate = overrideName || declared || srcDir.split(sep).pop() || "";
+    const slug = slugifySkillName(candidate);
+    if (!isValidSkillName(slug)) {
+        throw new Error(`Could not derive a skill name from ${sourcePath} — pass --name`);
+    }
+    const written = writeSkill(slug, raw, root);
+    const destDir = join(root, slug);
+    const files = [];
+    for (const sub of SKILL_ASSET_DIRS) {
+        const from = join(srcDir, sub);
+        if (!existsSync(from) || !statSync(from).isDirectory())
+            continue;
+        for (const entry of readdirSync(from, { withFileTypes: true })) {
+            if (!entry.isFile())
+                continue;
+            const target = join(destDir, sub, entry.name);
+            mkdirSync(join(destDir, sub), { recursive: true, mode: 0o700 });
+            writeFileSync(target, readFileSync(join(from, entry.name)), { mode: 0o600 });
+            files.push(`${sub}/${entry.name}`);
+        }
+    }
+    return { name: written.name, path: written.path, files };
+}
+/**
+ * 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 function syncSkillIndex(root = skillsDir()) {
+    const found = scanSkills(root);
+    const out = [];
+    for (const meta of found) {
+        const row = upsertSkillRow({
+            name: meta.name,
+            path: meta.path,
+            description: meta.description,
+            version: meta.version,
+            tags: meta.tags,
+            contentHash: meta.hash,
+            source: meta.source,
+        });
+        out.push({
+            ...meta,
+            repoId: row.repo_id,
+            uses: row.uses,
+            lastUsedAt: row.last_used_at,
+            modified: Boolean(row.origin_hash) && row.origin_hash !== meta.hash,
+        });
+    }
+    pruneSkillRows(found.map((s) => s.name));
+    return out;
+}
+export function listIndexedSkills(root = skillsDir()) {
+    return syncSkillIndex(root);
+}
+/**
+ * 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 function skillSummary(s) {
+    return {
+        name: s.name,
+        description: s.description,
+        version: s.version,
+        tags: s.tags,
+        path: s.path,
+        dir: s.dir,
+        hash: s.hash,
+        source: s.source,
+        ...("repoId" in s ? { repoId: s.repoId, uses: s.uses, lastUsedAt: s.lastUsedAt, modified: s.modified } : {}),
+    };
+}
+export function rankSkills(skills, query, limit = 3) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return [];
+    const ranked = [];
+    for (const skill of skills) {
+        const name = skill.name.toLowerCase();
+        const haystack = `${name} ${skill.description} ${skill.tags.join(" ")}`.toLowerCase();
+        let score = 0;
+        const reasons = [];
+        let hits = 0;
+        for (const token of tokens) {
+            if (name.includes(token)) {
+                score += 6;
+                hits += 1;
+            }
+            else if (haystack.includes(token)) {
+                score += token.length > 4 ? 3 : 2;
+                hits += 1;
+            }
+        }
+        if (hits === 0)
+            continue;
+        reasons.push(`match+${score}`);
+        // A skill that keeps getting used is a better bet than one nobody has opened.
+        if (skill.uses > 0) {
+            const useBoost = Math.min(4, Math.log2(skill.uses + 1) * 2);
+            score += useBoost;
+            reasons.push(`used×${skill.uses}`);
+        }
+        ranked.push({ ...skill, score, reasons });
+    }
+    return ranked.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, limit);
+}

package/docs/backlog.md

@@ -4,6 +4,7 @@ Updated after completing the Feature Map **Later** phase (local embedding model
 
 ## Shipped recently
 
+- **Agent Tasks Kanban** — per-project board + MCP `amem_task_*` + open tasks in context packets (complement to Memory facts)
 - FTS retrieval, claim staleness, supersede/conflict
 - Session-end **draft capture** + Memory approve/dismiss
 - Memory **edit / delete / pin / search**
@@ -37,6 +38,14 @@ Updated after completing the Feature Map **Later** phase (local embedding model
 
 ## Open
 
+- **Skills in backup/restore** — `createBackup` copies only the DB file, so `~/.amem/skills/`
+  is lost on restore. Now sharper than before: the `skills` index, `skill_drafts`, and
+  `skill_uses` tables all survive a restore while the SKILL.md bodies they point at do not,
+  so a restored machine gets an index of skills that no longer exist. Needs a decision:
+  make backups an archive (DB + skills dir), or keep backups DB-only, prune the index on
+  restore, and document skills as separately versioned.
+- **Skill drafts have no retention policy** — dismissed and applied rows accumulate. Memory
+  drafts have hygiene sweeps; skill drafts do not yet.
 - Prompt-pack before/after Stats benchmark; restore wizard polish; IT seat pack.
 - Decide one-time vs subscription (offline files cannot revoke on cancel unless you add `expires_at` and re-issue).
 - Optional vendored ONNX/MiniLM weights in a paid pack (external command is the local hook today).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamem/amem",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Local personal agent memory for Cursor and Claude Code. Private to your machine — never shared.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "templates",
     "docs",
     "ui-static",
+    "scripts/mcp-launch.sh",
     "scripts/mdm-offboard.sh",
     "scripts/postinstall.js"
   ],

package/scripts/mcp-launch.sh

@@ -0,0 +1,26 @@
+#!/bin/sh
+# amem MCP launcher for GUI hosts (Claude Desktop / Cowork).
+#
+# GUI apps are not launched from a login shell, so they inherit a minimal PATH
+# with no Homebrew and no nvm. A host configured with a bare `amem` or `node`
+# command registers the connector but never completes tool discovery. This
+# script resolves node at spawn time and execs the amem stdio MCP server.
+#
+# Set AMEM_NODE to pin a specific node binary. Extra args are passed through.
+DIR=$(cd "$(dirname "$0")/.." && pwd)
+NODE=""
+for c in \
+  "$AMEM_NODE" \
+  "$(command -v node 2>/dev/null)" \
+  /opt/homebrew/bin/node \
+  /usr/local/bin/node \
+  "$HOME/.homebrew/bin/node" \
+  /usr/bin/node
+do
+  if [ -n "$c" ] && [ -x "$c" ]; then NODE="$c"; break; fi
+done
+if [ -z "$NODE" ]; then
+  echo "amem-mcp: node 20+ not found. Set AMEM_NODE=/path/to/node in the host's MCP env." >&2
+  exit 1
+fi
+exec "$NODE" "$DIR/dist/cli.js" mcp "$@"

package/skills/amem-tasks/SKILL.md

@@ -0,0 +1,100 @@
+---
+description: Manage deferred tasks and Kanban lifecycle in local personal amem memory so work is preserved across sessions and available for context retrieval.
+---
+
+# amem-tasks
+
+Track deferred work, multi-step progress, and backlog items in local amem memory so tasks never get lost across chat sessions.
+
+## Privacy
+
+Memory is personal and stored under `~/.amem` on this machine. Tasks stay local and are never committed to remote repositories.
+
+## When to Use
+
+1. **Multi-step work**: When working on complex tasks or features with 3+ steps, create and manage tasks to track progress.
+2. **Deferred work**: When user or agent identifies follow-up work ("do X later", "verify Y after deploy", "refactor Z next week"), add it to the project backlog.
+3. **Session continuity & handoff**: Before ending a session or moving to a new topic, park unfinished items on the board.
+4. **Context retrieval**: Check `amem_task_list` or context packet `## Open tasks` / `## Tasks` to review current and completed work.
+
+## Task Status Lifecycle
+
+- `backlog` — Queued items, follow-ups, and ideas.
+- `next` — Prioritized tasks ready to start soon.
+- `doing` — Currently in progress (keep 1 active task at a time).
+- `blocked` — Stalled on external feedback, bug, or dependency.
+- `done` — Finished work (retained for context retrieval and history).
+
+## Available Tools
+
+### 1. MCP Tools (Cursor, Claude Code, Windsurf, Continue, Zed)
+
+- **`amem_task_add`**
+  ```json
+  {
+    "title": "Add rate limiter middleware to /api/auth",
+    "body": "Protect login endpoints against brute-force attempts",
+    "status": "backlog",
+    "anchors": ["src/api/auth.ts"]
+  }
+  ```
+
+- **`amem_task_list`**
+  ```json
+  {
+    "status": "doing",
+    "include_done": true
+  }
+  ```
+
+- **`amem_task_update`**
+  ```json
+  {
+    "id": "task_1234abcd",
+    "status": "doing",
+    "body": "Updated progress notes..."
+  }
+  ```
+
+- **`amem_task_complete`**
+  ```json
+  {
+    "id": "task_1234abcd"
+  }
+  ```
+
+### 2. CLI Commands (Terminal, Aider, Bash scripts)
+
+- **List tasks**:
+  ```bash
+  amem task list
+  amem task list --status doing
+  amem task list --include-done --all
+  ```
+
+- **Add task**:
+  ```bash
+  amem task add "Add rate limiter middleware" --body "Protect /api/auth" --status backlog --anchor src/api/auth.ts
+  ```
+
+- **Update task**:
+  ```bash
+  amem task update <id> --status doing
+  ```
+
+- **Complete task**:
+  ```bash
+  amem task complete <id>
+  ```
+
+- **Delete task**:
+  ```bash
+  amem task delete <id>
+  ```
+
+## Instructions for Agents
+
+1. **Deconstruct**: When starting a non-trivial user request, add the plan items to `amem_task_add`.
+2. **Track**: Mark the current working task as `doing` with `amem_task_update`.
+3. **Complete**: When a task is finished, call `amem_task_complete` immediately. Completed tasks stay stored in local memory and are searchable in context retrieval.
+4. **Learn**: If completing the task revealed durable repository facts (constraints, gotchas, ownership), save them with `amem_remember` or `amem-update-working-memory`.