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):

• 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

nora memory spaces list
nora memory spaces get sp_customer_history

Create

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

nora memory spaces update sp_customer_history \
  --name "Customer History (renamed)" \
  --access-scope-key tenant_id

Only flags passed change.

Delete

nora memory spaces delete sp_customer_history

Notes, nodes, and edges cascade.

Wiki notes

For paradigm=wiki spaces.

List

nora memory notes list sp_wiki
# Scope-filtered:
nora memory notes list sp_wiki --scope '{"user_id":"alice"}'

Upsert

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

nora memory notes grep sp_wiki \
  --query "refund" \
  --scope '{"team":"support"}' \
  --limit 20

Full-text search across notes.

Exclude (soft-prune)

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

# 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":"[e-mail]"}' \
  --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

# 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.

# 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.

# 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

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

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:

# Read all items, add new scope field, re-insert
# (specifics depend on your data model)

Find unattached spaces (candidates to delete)

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

nora memory notes list sp_wiki --json > wiki-snapshot.json