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

> 메모리 스페이스 관리 — 노트, 노드, 엣지, 세션, 진단.

메모리 스페이스가 Agent 가 기억하는 것 담음. `memory` CLI 가 전체 라이프사이클 처리: 스페이스 생성, 노트/노드/엣지 검사, 스코프된 세션 관리, 진단 (학습된 실패) 메모리와 상호작용.

네 스페이스 패러다임 ([메모리 스페이스](/ko/build/memory/spaces) 참고):

* **wiki** — 사람 저작 노트.
* **index** — 옵션 그래프 엣지 있는 벡터 인덱스 노드.
* **session** — 대화별 단기 메모리.
* **evolution** — 진단 메모리, 자동 채워짐.

명령이 패러다임에 적응 — wiki 는 `notes`, index 는 `nodes`/`edges`, session 은 `sessions`, evolution 은 `diagnostic`.

## 명령 그룹

* **스페이스**: `spaces list/get/create/update/delete`
* **Wiki 노트**: `notes list/upsert/grep/exclude`
* **Index 노드**: `nodes list/insert/update/set-position/exclude`
* **Index 엣지**: `edges list/insert/update/exclude`
* **진단**: `diagnostic list/recall/peek/exclude/restore`
* **세션**: `sessions scopes/turns/summary/count`
* **메타**: `log`, `scopes`, `connected-flows`

## 스페이스

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

플래그:

* `--slug` (필수) — 안정된 식별자.
* `--name` (필수) — 표시 이름.
* `--paradigm wiki|index|session|evolution` (필수).
* `--index-form vector|graph` — `index` 패러다임용, 그래프 엣지 활성 여부.
* `--kg-reference` — 지식 그래프 참조 스페이스로 표시.
* `--access-scope-key <key>` — 읽기/쓰기 격리에 쓰는 스코프 키.
* `--config <json>` — 추가 패러다임 특화 설정.

### Update

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

넘긴 플래그만 변경.

### Delete

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

노트, 노드, 엣지 cascade.

## Wiki 노트

`paradigm=wiki` 스페이스용.

### List

```bash theme={null}
nora memory notes list sp_wiki
# 스코프 필터:
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 "환불 플레이북" \
  --body @refunds.md \
  --scope '{"team":"support"}'
```

`--body` 가 인라인 텍스트, 경로용 `@file`, stdin 용 `-` 수용.

### Grep

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

노트에 걸친 전문 검색.

### Exclude (소프트 가지치기)

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

Excluded 노트가 리트리벌에 안 나타나지만 감사 로그에 남음.

## Index 노드·엣지

`paradigm=index` (with `index-form=graph`) 스페이스용 — 엔티티-관계 데이터 모델.

### 노드

```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 "Acme 의 VP Engineering" \
  --attrs '{"email":"alice@acme.com"}' \
  --scope '{"tenant":"acme"}'

# 요약 업데이트
nora memory nodes update node_abc --summary "Alice Smith (VP)"

# 캔버스에서 이동
nora memory nodes set-position node_abc --x 100 --y 200

# Exclude
nora memory nodes exclude node_abc
```

### 엣지

```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"}'

# 이름 변경
nora memory edges update edge_abc --predicate "manages"

# Exclude
nora memory edges exclude edge_abc
```

## 진단 메모리

Evolution 패러다임이 알려진 실패 패턴 축적.

```bash theme={null}
# 가장 재사용된 것 먼저 패턴 나열
nora memory diagnostic list --limit 20

# Recall — 재사용 카운터 bump (프로덕션 사용)
nora memory diagnostic recall \
  --category retrieval-miss \
  --flow support-agent \
  --failure-mode wrong-refund-policy

# Peek — 부수 효과 없음 (조사)
nora memory diagnostic peek \
  --category retrieval-miss \
  --flow support-agent \
  --failure-mode wrong-refund-policy

# 나쁜 패턴 exclude
nora memory diagnostic exclude pattern_abc --actor paul

# 복원
nora memory diagnostic restore pattern_abc
```

## 세션

`paradigm=session` 스페이스용.

```bash theme={null}
# 모든 활성 스코프
nora memory sessions scopes sp_chat

# 한 스코프의 턴
nora memory sessions turns sp_chat --scope '{"conversation_id":"c_abc"}' --limit 50

# 롤링 요약
nora memory sessions summary sp_chat --scope '{"conversation_id":"c_abc"}'

# 버퍼된 턴 카운트
nora memory sessions count sp_chat --scope '{"conversation_id":"c_abc"}'
```

## 메타

```bash theme={null}
nora memory log sp_customer_history       # 업데이트 로그 + 통계
nora memory scopes sp_customer_history    # 이 스페이스에서 쓴 스코프 값
nora memory connected-flows sp_customer_history   # Agent 붙은 flow
```

## 레시피

### 마크다운 파일에서 노트 벌크 삽입

```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
```

### 스페이스의 스코프 키 마이그레이션

`access-scope-key` 변경 — 옛 항목이 옛 스코프 유지; 새 항목이 새 것 사용. 마이그레이션이 수동:

```bash theme={null}
# 모든 항목 읽기, 새 스코프 필드 추가, 재삽입
# (구체는 데이터 모델에 따라 다름)
```

### 붙지 않은 스페이스 찾기 (삭제 후보)

```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 flow"
done
```

### 위키를 git 에 스냅샷

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