@iamem/amem 0.1.1 → 0.1.3

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

package/templates/policy.deny-default.toml

@@ -18,3 +18,8 @@ allowed_platforms = ["cursor", "claude"]
 
 # Empty = Memory must approve every draft. Do not auto-apply on managed fleets.
 auto_apply_kinds = []
+
+# Skills are instructions agents follow, so nothing reaches disk without a human.
+skills_enabled = true
+skill_write_approval = true
+skill_capture = true

package/templates/policy.example.toml

@@ -20,3 +20,11 @@ allowed_platforms = ["cursor", "claude"]
 # Optional: auto-apply low-risk draft kinds without Memory approve (empty = never).
 # Prefer leaving this empty on managed fleets.
 # auto_apply_kinds = ["structure"]
+
+# Skills — reusable procedures agents load on demand from ~/.amem/skills.
+# These are instructions an agent will follow, so treat them like code, not notes.
+skills_enabled = true
+# true = agent writes are staged for review instead of hitting disk.
+skill_write_approval = false
+# false = stop suggesting skills at session end.
+skill_capture = true