# okstra-memory AI Manual

## Source

- Skill source: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
- CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
- memory CLI: [`src/commands/memory/memory.mjs`](../../../src/commands/memory/memory.mjs)

## Purpose

`okstra-memory` manages the Memory Book in the user's home.

```text
~/.okstra/memory-book/
```

It is not a project-local `.okstra/` artifact. It can be used even without `<PROJECT_ROOT>/.okstra/project.json`.

## When to use

Use it when:

- The user explicitly asks to save, e.g. "remember this", "save the conversation", "organize and store this in okstra", "remember this", "save this decision".
- The user wants to search, list, read, or archive stored memory.

Do not use it when:

- The user is only brainstorming with no save request. In that case, ask a confirmation question first.
- The content should be kept as a project task artifact. In that case, use the brief/report/decision path of the relevant okstra task.

## safety rule

Do not save without an explicit save request. Do not store credentials, API keys, tokens, private personal data, or secrets. If the conversation includes sensitive material, exclude it from the summary and note the omission.

The CLI can also detect high-confidence secret shapes and refuse `memory add`. If refused, redact the content and retry.

## CLI availability

Check the help first.

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

If `okstra` is not on PATH, do not run `npx okstra@latest install` directly; tell the user to install it once and then retry.

## project-group selection

Every memory entry belongs to a project-group. Pick the group before storing or searching.

Enumerate existing groups:

```bash
okstra memory groups
```

Recommendations:

- the most-used existing group
- the second existing group
- Enter directly

For a personal note, recommend `private` first. If there is no group or no selection, use the CLI default `global`.

Pass the chosen group to `add`, `search`, and `list` as `--project-group <group>`. Omit the flag only when the user explicitly wants a cross-group search.

## Store procedure

Do not store the full conversation transcript. Extract only durable memory worth keeping long-term and turn it into a concise Markdown summary.

Include:

- the reason for storing
- source: `conversation`
- `--project` when the related project id is clear
- tags for search
- memory type

The `okstra memory --help` output is authoritative for the type values. Categories per the source:

- `decision`
- `preference`
- `requirement`
- `person`
- `project-hint`
- `follow-up`
- `context`

Store command shape:

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

Repeat `--tag` and `--project` as needed. Omit `--project` when no related project is clear.

Use `--yes` only when the user explicitly asked to save.

## search / read / archive

The default scope is the chosen project-group.

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

Read IDs from the fixed text rows. Show the user only a short summary plus the entry id/path.

## Output rules

- On store, summarize title, type, project-group, tags, and the generated id.
- On search, show the match count and the most relevant entry first.
- Run archive only when the user's intent is clear.
- Do not write into a project `.okstra/`.

## Forbidden patterns

- Auto-saving without an explicit request.
- Storing a secret/token/key.
- Storing the full transcript verbatim.
- Writing into `.okstra/` as if it were project-local task memory.
- Performing a cross-group search by default when the user did not ask for it.