> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora memory

> Manage memory spaces — notes, nodes, edges, sessions, diagnostic.

Memory spaces hold what Agents remember. The `memory` CLI handles the full lifecycle: create spaces, inspect notes/nodes/edges, manage scoped sessions, and interact with diagnostic (learned failure) memory.

Four space paradigms (see [Memory spaces](/build/memory/spaces)):

* **wiki** — human-authored notes.
* **index** — vector-indexed nodes with optional graph edges.
* **session** — per-conversation short-term memory.
* **evolution** — diagnostic memory, auto-populated.

Commands adapt to the paradigm — `notes` for wiki, `nodes`/`edges` for index, `sessions` for session, `diagnostic` for evolution.

## Command groups

* **Spaces**: `spaces list/get/create/update/delete`
* **Wiki notes**: `notes list/upsert/grep/exclude`
* **Index nodes**: `nodes list/insert/update/set-position/exclude`
* **Index edges**: `edges list/insert/update/exclude`
* **Diagnostic**: `diagnostic list/recall/peek/exclude/restore`
* **Sessions**: `sessions scopes/turns/summary/count`
* **Meta**: `log`, `scopes`, `connected-flows`

## Spaces

### List / get

```bash theme={null}
nora memory spaces list
nora memory spaces get sp_customer_history
```

### Create

```bash theme={null}
nora memory spaces create \
  --slug customer_history \
  --name "Customer History" \
  --paradigm index \
  --index-form graph \
  --kg-reference \
  --access-scope-key user_id
```

Flags:

* `--slug` (required) — stable identifier.
* `--name` (required) — display name.
* `--paradigm wiki|index|session|evolution` (required).
* `--index-form vector|graph` — for `index` paradigm, whether to enable graph edges.
* `--kg-reference` — mark as a knowledge-graph reference space.
* `--access-scope-key <key>` — the scope key used to isolate reads/writes.
* `--config <json>` — additional paradigm-specific config.

### Update

```bash theme={null}
nora memory spaces update sp_customer_history \
  --name "Customer History (renamed)" \
  --access-scope-key tenant_id
```

Only flags passed change.

### Delete

```bash theme={null}
nora memory spaces delete sp_customer_history
```

Notes, nodes, and edges cascade.

## Wiki notes

For `paradigm=wiki` spaces.

### List

```bash theme={null}
nora memory notes list sp_wiki
# Scope-filtered:
nora memory notes list sp_wiki --scope '{"user_id":"alice"}'
```

### Upsert

```bash theme={null}
nora memory notes upsert sp_wiki \
  --path playbooks/refunds.md \
  --title "Refund playbook" \
  --body @refunds.md \
  --scope '{"team":"support"}'
```

`--body` accepts inline text, `@file` for a path, or `-` for stdin.

### Grep

```bash theme={null}
nora memory notes grep sp_wiki \
  --query "refund" \
  --scope '{"team":"support"}' \
  --limit 20
```

Full-text search across notes.

### Exclude (soft-prune)

```bash theme={null}
nora memory notes exclude note_abc
```

Excluded notes don't appear in retrieval but remain in the audit log.

## Index nodes & edges

For `paradigm=index` (with `index-form=graph`) spaces — the entity-relationship data model.

### Nodes

```bash theme={null}
# List
nora memory nodes list sp_kg --scope '{"tenant":"acme"}' --limit 100

# Insert
nora memory nodes insert sp_kg \
  --summary "Alice Smith" \
  --kind person \
  --content "VP Engineering at Acme" \
  --attrs '{"email":"alice@acme.com"}' \
  --scope '{"tenant":"acme"}'

# Update summary
nora memory nodes update node_abc --summary "Alice Smith (VP)"

# Move on canvas
nora memory nodes set-position node_abc --x 100 --y 200

# Exclude
nora memory nodes exclude node_abc
```

### Edges

```bash theme={null}
# List
nora memory edges list sp_kg

# Insert
nora memory edges insert sp_kg \
  --src-node-id node_alice \
  --dst-node-id node_acme \
  --predicate "works_at" \
  --weight 1.0 \
  --scope '{"tenant":"acme"}'

# Rename
nora memory edges update edge_abc --predicate "manages"

# Exclude
nora memory edges exclude edge_abc
```

## Diagnostic memory

The evolution paradigm accumulates known failure patterns.

```bash theme={null}
# List patterns, most-reused first
nora memory diagnostic list --limit 20

# Recall — bumps the reuse counter (production usage)
nora memory diagnostic recall \
  --category retrieval-miss \
  --flow support-agent \
  --failure-mode wrong-refund-policy

# Peek — no side effect (investigation)
nora memory diagnostic peek \
  --category retrieval-miss \
  --flow support-agent \
  --failure-mode wrong-refund-policy

# Exclude a bad pattern
nora memory diagnostic exclude pattern_abc --actor paul

# Restore
nora memory diagnostic restore pattern_abc
```

## Sessions

For `paradigm=session` spaces.

```bash theme={null}
# All active scopes
nora memory sessions scopes sp_chat

# Turns in one scope
nora memory sessions turns sp_chat --scope '{"conversation_id":"c_abc"}' --limit 50

# Rolling summary
nora memory sessions summary sp_chat --scope '{"conversation_id":"c_abc"}'

# Buffered turn count
nora memory sessions count sp_chat --scope '{"conversation_id":"c_abc"}'
```

## Meta

```bash theme={null}
nora memory log sp_customer_history       # update log + stats
nora memory scopes sp_customer_history    # scope values used in this space
nora memory connected-flows sp_customer_history   # flows with Agents attached
```

## Recipes

### Bulk-insert notes from markdown files

```bash theme={null}
for f in playbooks/*.md; do
  path="playbooks/$(basename $f)"
  nora memory notes upsert sp_wiki \
    --path "$path" \
    --title "$(head -n1 $f | sed 's/^# //')" \
    --body @"$f"
done
```

### Migrate scope key on a space

Change `access-scope-key` — old items retain old scope; new items use new. Migration is manual:

```bash theme={null}
# Read all items, add new scope field, re-insert
# (specifics depend on your data model)
```

### Find unattached spaces (candidates to delete)

```bash theme={null}
for id in $(nora memory spaces list --json | jq -r '.[].id'); do
  n=$(nora memory connected-flows $id --json | jq 'length')
  [ "$n" = "0" ] && echo "$id — 0 flows"
done
```

### Snapshot a wiki to git

```bash theme={null}
nora memory notes list sp_wiki --json > wiki-snapshot.json
```