{"title":"메모리 모범 사례","slug":"memory-best-practices","category":"guides","summary":"효과적인 회상을 위해 메모리를 구조화하는 방법 — 카테고리, 키, 태그, 우선순위.","audience":["human","llm"],"tags":["guide","memory","best-practices","patterns"],"difficulty":"intermediate","updated":"2026-06-27","word_count":575,"read_minutes":3,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 메모리 모범 사례\n\n메모리를 어떻게 구조화하느냐가 유용성을 결정합니다. 이 가이드는 LLM이\n적절한 시기에 적절한 정보를 회상할 수 있도록 메모리를 카테고리화, 태깅,\n우선순위 지정하는 패턴을 다룹니다.\n\n## 카테고리: 가장 구체적인 것 선택\n\n| 카테고리 | 사용 용도 | 예시 |\n|----------|---------|---------|\n| `identity` | 사용자 이름, 역할, 연락처 정보 | `\"user_name\": \"Michael Schäfer\"` |\n| `preference` | 좋아함, 싫어함, 작업 스타일 | `\"communication\": \"Prefers concise responses\"` |\n| `fact` | 검증 가능한 사실 | `\"office_location\": \"Berlin, Germany\"` |\n| `project` | 프로젝트 상태, 결정 | `\"project_synapse\": \"v1.5.0 deployed\"` |\n| `skill` | 사용자 기술 | `\"skill_python\": \"Advanced, 10+ years\"` |\n| `mistake` | 피해야 할 과거 오류 | `\"mistake_npm_version\": \"Always bump version\"` |\n| `context` | 세션 관련 컨텍스트 | `\"current_focus\": \"Working on docs system\"` |\n| `note` | 기타 노트 | `\"note_idea\": \"Try Redis for caching\"` |\n\n> [!TIP]\n> 망설여지면 검증 가능한 정보에는 `fact`를, 그 외 모든 것에는 `note`를\n> 사용하십시오. 과도하게 카테고리화하지 마십시오 — 혼란스러운 `context`보다\n> 명확한 `fact`가 낫습니다.\n\n## 키: 의미 있는 식별자\n\n`key` 필드는 메모리의 식별자입니다. 의미 있고 안정적인 키를 사용하십시오:\n\n**좋은 키:**\n- `user_name`\n- `project_synapse_status`\n- `preference_communication_style`\n- `mistake_npm_version_bump`\n\n**나쁜 키:**\n- `mem_001` (의미 없음)\n- `temp` (설명적이지 않음)\n- `2026-06-27-note` (날짜는 회상에 도움되지 않음)\n\n### 키 명명 규칙\n\n- `snake_case` (밑줄이 있는 소문자)\n- 카테고리로 접두사: `preference_*`, `project_*`, `mistake_*`\n- 동사가 아닌 설명적인 명사 사용\n- 50자 이하로 유지\n\n## 태그: 검색 및 필터링용\n\n태그를 사용하면 빠른 필터링과 검색이 가능합니다. 메모리당 2-5개 태그 추가:\n\n```json\n{\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.\",\n \"tags\": [\"synapse\", \"deployment\", \"status\", \"v1.5.0\"]\n}\n```\n\n### 태그 패턴\n\n- **프로젝트 이름**: `synapse`, `synapse-mcp`, `synapse-chat`\n- **주제**: `deployment`, `ci`, `database`, `auth`\n- **상태**: `active`, `completed`, `blocked`\n- **우선순위 지표**: `urgent`, `long-term`\n\n> [!NOTE]\n> 태그는 대소문자를 구분하지 않습니다. 일관성을 위해 소문자를 사용하십시오.\n\n## 우선순위: 현실적으로\n\n| 우선순위 | 사용 용도 | 메모리 비율 |\n|----------|---------|---------------|\n| `critical` | 사용자 정체성, 법적 정보, 되돌릴 수 없는 결정 | ~5% |\n| `high` | 활성 프로젝트, 중요한 선호도 | ~20% |\n| `normal` | 대부분의 사실, 노트, 컨텍스트 | ~65% |\n| `low` | 일시적, 알면 좋음 | ~10% |\n\n> [!WARNING]\n> 모든 것을 `critical`로 표시하지 마십시오. 모든 것이 중요하면, 아무것도\n> 중요하지 않습니다. 잊었을 때 실제 피해를 초래할 것들에만 `critical`을\n> 사용하십시오.\n\n## 저장 여부\n\n### 항상 저장\n\n- 사용자 정체성 (이름, 이메일, 역할)\n- 장기 선호도\n- 프로젝트 결정 및 근거\n- 과거 실수 및 교훈\n- 사용자에게 한 약속\n\n### 저장하지 않음\n\n- 일시적 상태 (변수 사용)\n- 동일한 대화 기록 (채팅 시스템이 처리)\n- 민감한 데이터 (비밀번호, API 키)\n- 쉽게 도출 가능한 사실 (현재 날짜, 파일 내용)\n- 일시적 컨텍스트 (`context` 카테고리에 낮은 우선순위로 사용)\n\n## 메모리 업데이트\n\n동일한 `category` + `key`로 `/memory`를 POST하면 기존 메모리가 업데이트됩니다:\n\n```python\n# Initial store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Later: update with same key\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed. CI green.\", priority=\"high\")\n```\n\n> [!TIP]\n> 중복을 만들지 않고 업데이트할 수 있도록 안정적인 키를 사용하십시오. LLM은\n> 정보가 변경될 때 새 메모리를 만드는 대신 동일한 키를 다시 POST해야 합니다.\n\n## 메모리 라이프사이클\n\n```\nCreate → Active → Stale → Archive → Delete\n```\n\n- **Create**: 전체 컨텍스트로 POST /memory\n- **Active**: 자주 회상, 필요시 업데이트\n- **Stale**: 여전히 관련은 있지만 활발히 사용되지 않음 (우선순위 낮추기?)\n- **Archive**: 우선순위를 `low`로 설정, 역사적 참조용으로 유지\n- **Delete**: 더 이상 관련 없을 때 DELETE /memory/:id\n\n### 주기적 정리\n\n```python\n# Find memories not updated in 90 days\nold_memories = requests.get(\n f\"{URL}/memory/search?q=*\",\n headers={\"Authorization\": f\"Bearer {KEY}\"}\n)\n\nfor mem in old_memories[\"results\"]:\n if is_stale(mem, days=90):\n # Either delete or lower priority\n if is_obsolete(mem):\n delete_memory(mem[\"id\"])\n else:\n update_memory(mem[\"id\"], priority=\"low\")\n```\n\n## 패턴: 메모리 상속\n\n계층적 컨텍스트 (프로젝트 → 하위 프로젝트 → 작업)의 경우:\n\n```python\n# Parent project\nstore(\"project\", \"project_synapse\", \"Main Synapse project\", \n tags=[\"synapse\", \"parent\"], priority=\"high\")\n\n# Sub-project (tags link to parent)\nstore(\"project\", \"project_synapse_docs\", \"Docs system for Synapse\",\n tags=[\"synapse\", \"docs\", \"synapse-parent\"], priority=\"high\")\n\n# Specific task (tags link to sub-project)\nstore(\"project\", \"task_docs_loader\", \"Implement docs-loader.ts\",\n tags=[\"synapse\", \"docs\", \"task\"], priority=\"normal\")\n```\n\n그러면 LLM은 `q=synapse+docs`를 검색하여 모든 관련 메모리를 찾을 수 있습니다.\n\n## 패턴: 결정 로그\n\nLLM이 다시 논의하지 않도록 근거와 함께 결정을 저장:\n\n```python\nstore(\"fact\", \"decision_postgres_over_sqlite\",\n \"Chose PostgreSQL over SQLite for production. Reason: concurrent writes, \"\n \"FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.\",\n tags=[\"decision\", \"database\", \"postgres\", \"sqlite\"],\n priority=\"high\")\n```\n\n## 패턴: 실수 방지\n\n구체적인 방지 지침과 함께 실수를 저장:\n\n```python\nstore(\"mistake\", \"mistake_forget_version_bump\",\n \"Forgot to bump package.json version after changes. npm publish failed. \"\n \"FIX: Always run `npm version patch` before pushing. \"\n \"CI fails with 'version already exists' if you forget.\",\n tags=[\"npm\", \"ci\", \"publish\", \"version\"],\n priority=\"high\")\n```\n\n## 피해야 할 안티 패턴\n\n> [!WARNING]\n> - **대화 로그 저장** — 채팅 시스템이 처리\n> - **전체 파일 저장** — 스크립트 저장소 또는 외부 저장소 사용\n> - **일시적 상태 저장** — 변수 사용\n> - **비밀 저장** — 환경 변수 사용\n> - **메모리 중복** — 안정적인 키 사용\n> - **과도한 태깅** — 메모리당 2-5개 태그가 이상적\n> - **모든 것이 critical** — 우선순위를 현실적으로\n\n## 다음 단계\n\n- [Memory API](/docs/api/memory)\n- [영구 LLM 에이전트](/docs/guides/persistent-llm-agent)\n- [메모리 태깅 전략](/docs/llm-cookbook/memory-tagging-strategy)\n","content_html":"

메모리 모범 사례

\n

메모리를 어떻게 구조화하느냐가 유용성을 결정합니다. 이 가이드는 LLM이\n적절한 시기에 적절한 정보를 회상할 수 있도록 메모리를 카테고리화, 태깅,\n우선순위 지정하는 패턴을 다룹니다.

\n

카테고리: 가장 구체적인 것 선택

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
카테고리사용 용도예시
identity사용자 이름, 역할, 연락처 정보"user_name": "Michael Schäfer"
preference좋아함, 싫어함, 작업 스타일"communication": "Prefers concise responses"
fact검증 가능한 사실"office_location": "Berlin, Germany"
project프로젝트 상태, 결정"project_synapse": "v1.5.0 deployed"
skill사용자 기술"skill_python": "Advanced, 10+ years"
mistake피해야 할 과거 오류"mistake_npm_version": "Always bump version"
context세션 관련 컨텍스트"current_focus": "Working on docs system"
note기타 노트"note_idea": "Try Redis for caching"
\n
망설여지면 검증 가능한 정보에는 `fact`를, 그 외 모든 것에는 `note`를\n사용하십시오. 과도하게 카테고리화하지 마십시오 — 혼란스러운 `context`보다\n명확한 `fact`가 낫습니다.

키: 의미 있는 식별자

\n

key 필드는 메모리의 식별자입니다. 의미 있고 안정적인 키를 사용하십시오:

\n

좋은 키:

\n\n

나쁜 키:

\n\n

키 명명 규칙

\n\n

태그: 검색 및 필터링용

\n

태그를 사용하면 빠른 필터링과 검색이 가능합니다. 메모리당 2-5개 태그 추가:

\n
{\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",\n  "tags": ["synapse", "deployment", "status", "v1.5.0"]\n}

태그 패턴

\n\n
태그는 대소문자를 구분하지 않습니다. 일관성을 위해 소문자를 사용하십시오.

우선순위: 현실적으로

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
우선순위사용 용도메모리 비율
critical사용자 정체성, 법적 정보, 되돌릴 수 없는 결정~5%
high활성 프로젝트, 중요한 선호도~20%
normal대부분의 사실, 노트, 컨텍스트~65%
low일시적, 알면 좋음~10%
\n
모든 것을 `critical`로 표시하지 마십시오. 모든 것이 중요하면, 아무것도\n중요하지 않습니다. 잊었을 때 실제 피해를 초래할 것들에만 `critical`을\n사용하십시오.

저장 여부

\n

항상 저장

\n\n

저장하지 않음

\n\n

메모리 업데이트

\n

동일한 category + key로 /memory를 POST하면 기존 메모리가 업데이트됩니다:

\n
# Initial store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Later: update with same key\nstore("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
중복을 만들지 않고 업데이트할 수 있도록 안정적인 키를 사용하십시오. LLM은\n정보가 변경될 때 새 메모리를 만드는 대신 동일한 키를 다시 POST해야 합니다.

메모리 라이프사이클

\n
Create → Active → Stale → Archive → Delete
\n

주기적 정리

\n
# Find memories not updated in 90 days\nold_memories = requests.get(\n    f"{URL}/memory/search?q=*",\n    headers={"Authorization": f"Bearer {KEY}"}\n)\n\nfor mem in old_memories["results"]:\n    if is_stale(mem, days=90):\n        # Either delete or lower priority\n        if is_obsolete(mem):\n            delete_memory(mem["id"])\n        else:\n            update_memory(mem["id"], priority="low")

패턴: 메모리 상속

\n

계층적 컨텍스트 (프로젝트 → 하위 프로젝트 → 작업)의 경우:

\n
# Parent project\nstore("project", "project_synapse", "Main Synapse project", \n      tags=["synapse", "parent"], priority="high")\n\n# Sub-project (tags link to parent)\nstore("project", "project_synapse_docs", "Docs system for Synapse",\n      tags=["synapse", "docs", "synapse-parent"], priority="high")\n\n# Specific task (tags link to sub-project)\nstore("project", "task_docs_loader", "Implement docs-loader.ts",\n      tags=["synapse", "docs", "task"], priority="normal")

그러면 LLM은 q=synapse+docs를 검색하여 모든 관련 메모리를 찾을 수 있습니다.

\n

패턴: 결정 로그

\n

LLM이 다시 논의하지 않도록 근거와 함께 결정을 저장:

\n
store("fact", "decision_postgres_over_sqlite",\n      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "\n      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",\n      tags=["decision", "database", "postgres", "sqlite"],\n      priority="high")

패턴: 실수 방지

\n

구체적인 방지 지침과 함께 실수를 저장:

\n
store("mistake", "mistake_forget_version_bump",\n      "Forgot to bump package.json version after changes. npm publish failed. "\n      "FIX: Always run `npm version patch` before pushing. "\n      "CI fails with 'version already exists' if you forget.",\n      tags=["npm", "ci", "publish", "version"],\n      priority="high")

피해야 할 안티 패턴

\n

다음 단계

\n\n","urls":{"html":"/docs/guides/memory-best-practices","text":"/docs/guides/memory-best-practices?format=text","json":"/docs/guides/memory-best-practices?format=json","llm":"/docs/guides/memory-best-practices?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}