@iamem/amem 0.1.2 → 0.1.3

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.1.3",
   "description": "Local personal agent memory for Cursor and Claude Code. Private to your machine — never shared.",
   "type": "module",
   "bin": {

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`.

package/skills/amem-write-skill/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: amem-write-skill
+description: Write a durable procedure from this session into local amem skills.
+---
+
+# amem-write-skill
+
+Turn a non-trivial workflow you just worked out into a reusable skill stored in local amem.
+
+Use this when an amem context packet shows a **Worth saving as a skill** or **Skill worth
+revising** nudge, or when you notice on your own that you solved something worth repeating.
+
+## Privacy
+
+- Skills are stored locally under `~/.amem/skills` and never leave this machine.
+- Do not store secrets, tokens, credentials, connection strings, or private personal data.
+  amem scans content and will refuse writes that look like credentials.
+- Do not paste proprietary company LLM instructions — write the procedure, not the prompt.
+
+## When to write one
+
+Write a skill when at least one of these is true:
+
+- You worked out a multi-step workflow that will come up again.
+- You hit errors or dead ends and found the path that actually works.
+- The user corrected your approach and the correction generalizes.
+
+Do **not** write a skill for a one-off fix, a single command, or anything already obvious
+from the repo's README. A small durable fact belongs in memory (`amem_remember`), not here.
+The split: memory holds facts that should always be in context; skills hold procedures that
+should load only when relevant.
+
+## Steps
+
+1. Check what already exists so you update instead of duplicating:
+
+   ```bash
+   amem skills list
+   ```
+
+   If a related skill exists, load it and revise it rather than writing a second one:
+
+   ```bash
+   amem skills show <name>
+   ```
+
+2. Draft the SKILL.md. Keep the description under about 80 characters — it is the only
+   thing agents see until they load the body, so it must say *when to use this*, not just
+   what it is.
+
+3. Save it with the `amem_skill_save` MCP tool, passing `name`, `description`, and
+   `content`. Prefer that over writing files directly so the content scan runs.
+
+## Format
+
+```markdown
+---
+name: deploy-staging
+description: Deploy the staging server and verify the health endpoint
+tags: [deploy, staging]
+---
+
+# Deploy Staging
+
+## When to use
+Trigger conditions — the situation where this procedure applies.
+
+## Procedure
+1. Concrete step with the real command.
+2. Next step.
+
+## Pitfalls
+- The dead end you hit, and what got you past it.
+
+## Verification
+How to confirm it actually worked.
+```
+
+## Pitfalls
+
+- **Vague descriptions.** "Helps with deploys" is useless for ranking. Name the trigger.
+- **Transcribing the chat.** Write the procedure that worked, not the exploration that led
+  to it. Skip the wrong turns except as entries under Pitfalls.
+- **Inventing steps.** Only include commands you actually ran and saw work.
+- **Duplicates.** Revising an existing skill beats adding a near-copy.
+
+## Verification
+
+```bash
+amem skills list          # your skill appears with its description
+amem skills show <name>   # body reads as a procedure someone else could follow
+```
+
+If a write is staged instead of saved, an approval gate is on. Review it with:
+
+```bash
+amem skills drafts
+amem skills approve <draft-id>
+```

package/templates/cursor-rule.mdc

@@ -1,23 +1,33 @@
 ---
-description: Use local personal amem memory before broad codebase exploration
+description: Use local personal amem memory and tasks before broad codebase exploration
 globs:
 alwaysApply: true
 ---
 
 <!-- Generated by amem. Safe to commit: contains no memory contents. -->
 
-# amem local memory
+# amem local memory & tasks
 
-amem injects matching local memory into Cursor automatically (session start + each prompt). Treat that packet as the first map of this repo.
+amem injects matching local memory and open tasks into Cursor automatically (session start + each prompt). Treat that packet as the first map of this repo.
 
 1. Prefer amem file anchors over broad greps and multi-folder reads.
 2. Still verify current code before editing — memory can be stale. Trust **fresh** claims more; re-check anything marked **stale**.
 3. Use the **Why:** line as ranking explainability, not as proof.
-4. After durable learnings, the stop hook queues a compact **session draft** (and may queue **miss→learn** drafts). Approve in `amem ui` → Memory, or run `amem-update-working-memory` for higher-quality facts.
-5. Cross-repo personal prefs may appear with Why reason `personal` — they are local “how I work” notes, not org wiki.
+4. **Agent Tasks & Kanban:**
+   - Use `amem_task_add` to record deferred work, follow-ups, or multi-step tasks so they don't get lost across chat sessions.
+   - Update tasks to `doing` with `amem_task_update` when starting work.
+   - Mark completed tasks with `amem_task_complete` as soon as finished so completed tasks are preserved in history and context retrieval.
+   - Query `amem_task_list` (or check `## Open tasks` in context) to see pending and completed tasks.
+5. **Skills (procedural memory):**
+   - A `## Relevant skills` section lists names and descriptions only. If one looks like it applies, call `amem_skill_view` to load the procedure **before** working it out yourself.
+   - When you solve something worth repeating — a multi-step workflow, a dead end you found the way past, or a correction the user gave you — save it with `amem_skill_save`. The `amem-write-skill` skill has the format.
+   - A `## Worth saving as a skill` or `## Skill worth revising` note in the packet means amem already spotted one. Write it up if you agree; it is a suggestion, not an order.
+   - Skills are procedures. Small durable facts still belong in memory via `amem_remember`.
+6. After durable learnings, the stop hook queues a compact **session draft** (and may queue **miss→learn** drafts). Approve in `amem ui` → Memory, or run `amem-update-working-memory` for higher-quality facts.
+7. Cross-repo personal prefs may appear with Why reason `personal` — they are local “how I work” notes, not org wiki.
 
 Do not re-run `amem context` unless the injected packet is empty or clearly wrong.
 
 Memory is personal and stored under `~/.amem` on this machine. Do not commit exports, backups, or database copies to shared remotes.
 
-Open the local UI anytime with `amem ui` (Setup, Memory drafts, Stats).
+Open the local UI anytime with `amem ui` (Setup, Memory drafts, Tasks, Skills, Stats).