> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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
```

노트, 노드, 엣지가 함께 지워짐.

## 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: 재사용 카운터 올림 (프로덕션 사용)
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 (flow 0개)"
done
```

### 위키를 git에 스냅샷

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