# Commands and tools

This document lists implemented v1 commands/tools only. All memory is workspace-scoped and advisory. Store-unavailable failures are explicit and do not pretend success.

## Commands

### `/memory [help|status]`

Shows command help and a status summary. Unknown subcommands return usage.

### `/memory-stats`

Shows loaded/config state, DB path/status, workspace, table counts, FTS5 availability/fallback information, and last consolidation status.

### `/memory-search <query>`

Searches implemented memory types. Retrieval order is exact id/key, FTS keyword search when available, then deterministic substring fallback. Results include type/id/title or snippet where available. Empty queries return usage.

### `/memory-lessons [query]`

Lists lessons, or searches lessons when a query is supplied.

### `/memory-forget <id-or-prefix>`

Soft-deletes an active fact or lesson by exact id or safe unambiguous prefix. Empty, too-short, ambiguous, or unknown prefixes fail safely.

### `/memory-last`

Shows the latest non-deleted session handoff for the current workspace, or a clear no-prior-handoff message.

### `/memory-save [note]`

Runs deterministic consolidation for the current session/manual note. It saves or updates a compact handoff and stores only conservative durable fact/lesson candidates that pass filters and confidence/secret checks. It may report a clear no-op when input is insufficient.

### `/memory-clear`

Opens a confirmation dialog, deletes all memory for the current workspace if confirmed, and recreates an empty memory store so the session can continue safely.

### `/plan`

Resumes/shows the active plan summary.

### `/plan list [all]`

Lists active plans. Add `all` to include done and cancelled plans.

### `/plan activate <plan-id-or-prefix>`

Marks a plan active and bumps it to the default for `/plan`, `/plan next`, and `/plan resume` when several plans exist.

### `/plan close <plan-id-or-prefix>`

Marks a plan done so it is hidden from active defaults.

### `/plan cancel <plan-id-or-prefix> [reason]`

Marks a plan cancelled so it remains visible in history without being treated as completed.

### `/plan next [plan-id-or-prefix]`

Shows the next actionable task. Selection prefers current `IN_PROGRESS`, then highest-priority `TODO`, and skips blocked/done/cancelled/deleted tasks.

### `/plan resume [plan-id-or-prefix]`

Shows plan status, tasks, blockers, and next work.

### `/plan done <task-id-or-prefix>`

Marks a task done.

### `/plan block <task-id-or-prefix> <reason>`

Marks a task blocked with a reason.

### `/plan cancel-task <task-id-or-prefix> [reason]`

Marks a task cancelled so it is excluded from next-task selection without being treated as completed.

### `/decision <summary>`

Logs a durable active decision. Additional fields are available through tools.

### `/decision delete <id> [reason]`

Soft-deletes a mistaken decision so it no longer appears in normal retrieval.

### `/progress <status> <description>`

Logs a durable progress entry. Status is normalized by the progress store.

### `/progress delete <id> [reason]`

Soft-deletes a mistaken progress entry so it no longer appears in normal retrieval.

### `/graph <item-id-or-prefix>`

Shows graph neighbors for a graph item or item id/prefix. Unknown or ambiguous inputs fail with a clear error.

### `/graph delete-link <id> [reason]`

Soft-deletes a mistaken graph link.

### `/graph delete-item <type> <id> [reason]`

Soft-deletes a mistaken graph item and its active adjacent links. This removes the graph materialization, not the underlying decision/task/fact/progress record.

## Tools

Tool responses return human-readable `content` and structured `details` with ids/statuses/timestamps/provenance where available.

### Memory tools

#### `memory_stats`

Input: no required parameters.

Output: effective config, DB status/path, workspace, table counts, FTS5 status, and last consolidation status.

#### `memory_remember`

Input: `type`, plus fields for facts or lessons.

- Fact input: `type: "fact"`, `key`, `value`, optional `confidence`, `source`, `tags`, `provenance`.
- Lesson input: `type: "lesson"`, `content`, optional `category`, `negative`, `confidence`, `source`, `tags`, `provenance`.
- `pattern` and `custom_data` are accepted by schema but return explicit unsupported-type results in v1.

Behavior: stores facts/lessons after deterministic validation. Lower-confidence conflicting facts do not overwrite higher-confidence facts. Exact duplicate lessons are rejected. Secret-like content is rejected.

#### `memory_forget`

Input: `id`, optional `reason`.

Behavior: soft-deletes facts/lessons only. Ambiguous prefixes fail safely.

#### `memory_lessons`

Input: optional `query`, `category`, `includeDeleted`, `limit`.

Output: matching lessons for the current workspace.

#### `memory_search`

Input: `query`, optional `includeDeleted`, `limit`.

Output: mixed implemented memory types with `retrievalTier` (`exact`, `fts`, or `substring`), plus snippet/rank when FTS provides it.

### Session tools

#### `session_handoff_save`

Input: optional summary fields: `title`, `summary`, `handoffText`, `accomplished`, `decisions`, `filesMentioned`, `filesTouched`, `openQuestions`, `blockers`, `nextSteps`, `verified`, `notVerified`, and `source`.

Behavior: saves or updates a compact session summary; redacts secret-like text.

#### `session_handoff_get`

Input: optional `sessionId`, `includeDeleted`.

Output: latest or selected handoff.

#### `memory_recall_last`

Input: optional `includeDeleted`.

Output: latest non-deleted handoff for the workspace, or empty result.

### Plan/task tools

#### `plan_create`

Input: `title`, optional `goal`, `source`.

Output: created active plan.

#### `plan_get`

Input: optional `id`/prefix.

Output: current active plan or selected plan with tasks.

#### `plan_list`

Input: optional `includeDone`, optional `limit`.

Output: active plans by default, or all matching plans when `includeDone` is true.

#### `plan_next`

Input: optional `id`/prefix.

Output: next actionable task and plan.

#### `plan_resume`

Input: optional `id`/prefix.

Output: plan summary with open/blocked/done task counts.

#### `plan_activate`

Input: `id`, optional `reason`.

Output: selected plan marked `ACTIVE` so default plan operations resolve to it.

#### `plan_close`

Input: `id`, optional `reason`.

Output: selected plan marked `DONE` so it no longer appears in active defaults.

#### `plan_cancel`

Input: `id`, optional `reason`.

Output: selected plan marked `CANCELLED` so it no longer appears in active defaults but remains distinct from completed plans.

#### `task_add`

Input: `title`, optional `planId`, `description`, `priority`, `parentTaskId`.

Output: created task.

#### `task_update`

Input: `id`, optional `planId`, `title`, `description`, `status`, `priority`, `blockedReason`, `parentTaskId`.

Output: updated task.

#### `task_complete`

Input: `id`, optional `planId`, `reason`.

Output: task marked `DONE`.

#### `task_block`

Input: `id`, `reason`, optional `planId`.

Output: task marked `BLOCKED` with blocked reason.

#### `task_cancel`

Input: `id`, optional `planId`, `reason`.

Output: task marked `CANCELLED`.

### Decision tools

#### `decision_log`

Input: `summary`, optional `rationale`, `implementationDetails`, `status`, `active`, `tags`, and `provenance`.

Output: created active decision. Secret-like durable text is rejected.

#### `decision_search`

Input: optional `query`, `status`, `includeSuperseded`, `includeDeleted`, `limit`.

Output: matching decisions; superseded/deleted records are hidden by default.

#### `decision_update`

Input: `id`, optional fields to update (`summary`, `rationale`, `implementationDetails`, `status`, `active`, `tags`, `provenance`).

Output: updated decision.

#### `decision_delete`

Input: `id`, optional `reason`.

Output: soft-deleted decision. Deleted decisions are hidden from normal retrieval unless explicitly included.

#### `decision_supersede`

Input: `id`, optional `supersededBy`, `replacementSummary`, `reason`, `tags`, and `provenance`.

Output: superseded decision and optional replacement link.

### Progress tools

#### `progress_log`

Input: `status`, `description`, optional `evidence`, `targetType`, `targetId`, `parentId`, `verification`, and `provenance`.

Output: created progress entry. Secret-like durable text is rejected.

#### `progress_search`

Input: optional `query`, `status`, `includeDeleted`, `limit`.

Output: matching progress entries.

#### `progress_update`

Input: `id`, optional `status`, `description`, `evidence`, `targetType`, `targetId`, `parentId`, `verification`, and `provenance`.

Output: updated progress entry.

#### `progress_delete`

Input: `id`, optional `reason`.

Output: soft-deleted progress entry. Deleted progress entries are hidden from normal retrieval unless explicitly included.

### Graph tools

#### `graph_link`

Input: `sourceType`, `sourceId`, `targetType`, `targetId`, `relationship`, optional `metadata`.

Behavior: validates item existence/workspace for implemented item types, creates graph items as needed, then creates a directed link. Cross-workspace links fail safely. Secret-like metadata is rejected.

#### `graph_delete`

Input: `kind` (`item` or `link`), `id`, optional `type`, optional `reason`.

Output: soft-deleted graph link or graph item. Deleting a graph item also soft-deletes its active adjacent graph links.

#### `graph_neighbors`

Input: `id`, optional `type`, `direction`, `relationship`, `includeDeleted`, `limit`.

Output: immediate graph neighbors; deleted linked items are hidden by default or marked unavailable when requested.

#### `graph_trace`

Input: `id`, optional `type`, `direction`, `relationship`, `includeDeleted`, `limit`, `maxDepth`.

Output: bounded, cycle-safe traversal. Defaults are intentionally small.

#### `graph_search`

Input: `query`, optional `type`, `includeDeleted`, `limit`.

Output: graph item label matches.

## Examples

Command examples:

```sh
/memory-stats
/memory-search sqlite wal
/memory-lessons migrations
/memory-forget 4f2a9c
/memory-save Finished schema docs; next run pack check.
/plan next
/plan block 2b91 waiting for reviewer input
/decision Use deterministic summarization for v1 handoffs
/decision delete 8c2f1d1 mistaken duplicate
/progress verified npm test passed
/progress delete 9f21c3e entered by mistake
/graph 7d3e
/graph delete-link 4ab9c2e cleanup wrong relationship
```

Tool call examples:

```json
[
  { "tool": "memory_remember", "input": { "type": "fact", "key": "default_db_path", "value": ".pi/memory/memory.sqlite", "confidence": 0.95, "source": "README" } },
  { "tool": "memory_remember", "input": { "type": "lesson", "content": "Keep stored memory advisory and verify it against current files.", "category": "safety" } },
  { "tool": "memory_search", "input": { "query": "default_db_path", "limit": 5 } },
  { "tool": "session_handoff_save", "input": { "summary": "Reviewed docs", "nextSteps": ["Run pack check"], "verified": ["typecheck passed"] } },
  { "tool": "plan_create", "input": { "title": "Slice 13 review", "goal": "Verify docs and package contents" } },
  { "tool": "task_add", "input": { "title": "Inspect npm pack dry-run", "priority": 1 } },
  { "tool": "decision_log", "input": { "summary": "Mark vector retrieval as v2", "rationale": "No embedding implementation exists in v1" } },
  { "tool": "decision_delete", "input": { "id": "decision-id", "reason": "created by mistake" } },
  { "tool": "progress_log", "input": { "status": "verified", "description": "pack:check excludes tests and plan artifacts", "verification": "npm run pack:check" } },
  { "tool": "progress_delete", "input": { "id": "progress-id", "reason": "wrong entry" } },
  { "tool": "graph_link", "input": { "sourceType": "decision", "sourceId": "decision-id", "targetType": "task", "targetId": "task-id", "relationship": "supports" } },
  { "tool": "graph_delete", "input": { "kind": "link", "id": "graph-link-id", "reason": "linked by mistake" } }
]
```

Outputs include a text summary in `content` plus structured `details`. Mutation examples return ids/status/timestamps and search examples return matched records with retrieval metadata when applicable.

## Common failure modes

- `store_unavailable`: session has not initialized the DB or memory is disabled.
- `invalid_input` / usage errors: missing required fields or malformed command args.
- `secret_rejected`: durable input contained secret-like content.
- `not_found`: no active workspace-scoped record matched.
- `ambiguous`: an id prefix matched multiple records.
- `unsupported_type`: v1 does not implement requested future memory type.

## V1/V2 boundary

V1 has no embeddings/vector search, cloud sync, import/export, advanced graph visualization, multi-process DB locking, or required LLM behavior.