1 files changed, 80 insertions, 0 deletions
diff --git a/makima/src/daemon/skills/directive.md b/makima/src/daemon/skills/directive.md
index 7c55cf8..68d9277 100644
--- a/makima/src/daemon/skills/directive.md
+++ b/makima/src/daemon/skills/directive.md
@@ -76,6 +76,86 @@ Updates the goal and bumps `goalUpdatedAt`. If the directive is `idle`, it react
 makima directive pause
 ```
 
+## Memory Commands
+
+Directives have an optional key-value memory system that persists across steps and planning cycles. Use memory to share context, decisions, and learned information between steps — so downstream tasks don't need to re-discover what earlier steps already figured out.
+
+### Set a Memory Entry
+```bash
+makima directive memory-set <key> <value>
+```
+Stores a key-value pair in the directive's memory. If the key already exists, the value is overwritten. Keys are strings; values are strings (use JSON encoding for structured data).
+
+**Example:**
+```bash
+makima directive memory-set "db_schema_version" "3"
+makima directive memory-set "auth_pattern" "JWT with refresh tokens stored in httpOnly cookies"
+makima directive memory-set "api_base_path" "/api/v2"
+```
+
+### Get a Memory Entry
+```bash
+makima directive memory-get <key>
+```
+Retrieves the value for a specific key. Returns the value if found, or an error if the key does not exist.
+
+**Example:**
+```bash
+makima directive memory-get "db_schema_version"
+```
+
+### List All Memory Entries
+```bash
+makima directive memory-list
+```
+Returns all key-value pairs stored in the directive's memory. Useful for understanding what context is available before starting work on a step.
+
+### Delete a Memory Entry
+```bash
+makima directive memory-delete <key>
+```
+Removes a single key-value pair from memory.
+
+**Example:**
+```bash
+makima directive memory-delete "deprecated_config_key"
+```
+
+### Clear All Memory
+```bash
+makima directive memory-clear
+```
+Removes **all** key-value pairs from the directive's memory. Use with caution — this is irreversible.
+
+### Batch Set Memory Entries
+```bash
+makima directive memory-batch-set --json '{"key1": "value1", "key2": "value2"}'
+```
+Sets multiple key-value pairs in a single operation. Existing keys are overwritten; keys not mentioned are left unchanged.
+
+**Example:**
+```bash
+makima directive memory-batch-set --json '{"framework": "axum", "orm": "sqlx", "test_runner": "cargo test"}'
+```
+
+## Using Memory Effectively
+
+### When to Write Memory
+- **During planning**: Record architectural decisions, technology choices, and file layout patterns
+- **After step completion**: Save discovered information (e.g., generated IDs, API endpoints, schema details)
+- **When context matters**: Store anything a downstream step would need to avoid re-exploring the codebase
+
+### When to Read Memory
+- **At step start**: Check `memory-list` to see what context previous steps have provided
+- **Before making decisions**: Check if an earlier step already made a relevant architectural choice
+- **During re-planning**: Read memory to understand what was learned in previous iterations
+
+### Best Practices
+- Use descriptive, namespaced keys (e.g., `auth.strategy`, `db.migration_count`, `api.base_url`)
+- Store concise but complete values — enough for another task to act on without guessing
+- Clean up stale entries when the directive's goal changes significantly
+- Use `memory-batch-set` when recording multiple related decisions at once
+
 ## Orchestration Workflow
 
 ### Initial Setup