---
name: okstra-memory
description: Use when the user wants to preserve, remember, store, recall, search, or archive AI/human conversation notes in okstra's global Memory Book. Trigger words include "organize and store this in okstra", "memory-book", "remember this for me", "save the conversation", "summarize and save", "remember this", "store this conversation", "save this decision", "search the memory-book", "find the note I saved", "recall a saved decision".
---

# okstra-memory

Manage the user-home Memory Book at `~/.okstra/memory-book/`.

Memory Book is **global user memory**, not a project-local task artifact.
It does not require `<PROJECT_ROOT>/.okstra/project.json`, and it must not
write into any project `.okstra/` directory unless a separate okstra task
explicitly cites a memory entry later.

## When to use

- The user says "organize and store this in okstra", "remember this for me", "save the conversation",
  "remember this", or similar.
- The user asks to search, list, show, or archive stored conversation memory.
- The user wants decisions, preferences, requirements, people/context notes,
  or follow-ups from the current conversation saved for future retrieval.

## Safety rule

Only save when the user explicitly asks to save/remember/store. If the user is
only brainstorming, ask one concise confirmation question before writing.
Never store credentials, API keys, tokens, private personal data, or secrets.
If the conversation includes sensitive material, omit it and note the omission
in the stored summary. As a backstop, `okstra memory add` itself refuses content
matching high-confidence secret shapes (private-key blocks, AWS/GitHub/Slack/Google
tokens, JWTs) and exits non-zero — redact and retry if you hit it.

## Step 0: Check CLI availability

Run as a separate Bash tool call with literal leading token:

```bash
okstra memory --help
```

If `okstra` is not on PATH, tell the user:

`okstra not installed — run npx okstra@latest install once, then retry this skill.`

Do not use `npx` from this skill.

## Step 1: Pick the project-group (always first)

Every Memory Book entry belongs to a **project-group** — a search-scoping label
that partitions memory by organization or context (e.g. `acme`, `globex`,
`private` for personal notes). This selection comes **before** storing or
searching so the rest of the skill can scope to it.

1. Enumerate existing groups to build recommendations:

   ```bash
   okstra memory groups
   ```

2. Present a 3-option picker (most-used existing group, next existing group,
   then always `Enter directly`). For a personal note, recommend `private` as the
   first option. If `groups` is empty or the user makes no selection, the
   default group is `global` (the CLI default in `memory.mjs`).
3. Carry the chosen group name into every `add` (`--project-group <name>`) and
   into scoped `search`/`list` (`--project-group <name>`) below. Omit the flag
   only when the user explicitly wants a cross-group search.

## Store current conversation

1. Extract only durable memory from the conversation and tag each with a
   `--type`. The authoritative `--type` value list is the `okstra memory --help`
   output read in Step 0; the categories below mirror it:
   - decision
   - preference
   - requirement
   - person
   - project-hint
   - follow-up
   - context
2. Write a concise Markdown summary, not a full transcript.
3. Include provenance:
   - why it is being stored
   - source: `conversation`
   - related project ids if clearly stated
   - tags useful for search
4. Store with `--yes` because the user's save request is already explicit.

Command shape:

```bash
okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --project-group <group> --tag <tag> --project <id> --source conversation --yes
```

Use repeated `--tag` / `--project` flags when needed. Omit `--project` when no
project is clearly related. `--project-group` is the group chosen in Step 1.

## Search / read / archive

Scope reads to the chosen project-group by default; drop `--project-group` only
for an explicit cross-group search:

```bash
okstra memory search "<query>" --project-group "<group>"
okstra memory list --project-group "<group>" --tag "<tag>"
okstra memory groups            # list groups with entry counts
okstra memory show "<memory-id>"
okstra memory archive "<memory-id>"
```

Use the fixed text rows emitted by these commands, then present a short human
summary to the user.