{"title":"메모리 태깅 전략","slug":"memory-tagging-strategy","category":"llm-cookbook","summary":"효과적인 검색과 필터링을 위해 메모리를 태깅하는 방법 — 확장 가능한 태깅 시스템.","audience":["llm"],"tags":["cookbook","tagging","memory","strategy"],"difficulty":"intermediate","updated":"2026-06-27","word_count":314,"read_minutes":2,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 메모리 태깅 전략\n\n태그는 확장 가능한 메모리 검색의 비결입니다. 이 가이드는 적절한 시기에\n올바른 메모리가 돌아오도록 메모리를 태깅하는 방법을 보여줍니다.\n\n## 태그가 중요한 이유\n\n태그가 없으면, 평면적인 전문 검색만 있습니다. 태그가 있으면, 구조화된\n탐색이 가능합니다:\n\n```bash\n# Without tags: search everything\nGET /memory/search?q=docker\n\n# With tags: filter by project + technology\nGET /memory/search?q=deployment&tag=synapse&tag=docker\n```\n\n태그를 통해:\n\n- **빠른 필터링** — `GET /memory/by-tag?tag=production`\n- **범위 지정 검색** — `?q=auth&tag=project-x`\n- **그룹화** — 프로젝트의 모든 \"mistake\" 메모리 찾기\n- **교차 참조** — 태그를 공유하는 메모리는 관련됨\n\n## 태깅 스키마\n\n### 프로젝트 태그\n\n프로젝트 이름을 태그로 사용:\n\n```\nsynapse, synapse-mcp, synapse-chat, synapse-sdk\n```\n\n### 기술 태그\n\n기술 이름 사용:\n\n```\ndocker, kubernetes, postgres, fastify, react, typescript\n```\n\n### 주제 태그\n\n주제 카테고리 사용:\n\n```\ndeployment, ci-cd, auth, database, frontend, backend, security\n```\n\n### 상태 태그\n\n상태 지표 사용:\n\n```\nactive, completed, blocked, deprecated\n```\n\n### 유형 태그\n\n유형 지표 사용:\n\n```\ndecision, mistake, pattern, reference, todo\n```\n\n## 태깅 규칙\n\n### 규칙 1: 메모리당 2-5개 태그\n\n태그가 너무 적으면 검색 가능성이 떨어집니다. 너무 많으면 노이즈입니다.\n\n```json\n// Good: 3 relevant tags\n{ \"tags\": [\"synapse\", \"deployment\", \"docker\"] }\n\n// Bad: 1 tag (too narrow)\n{ \"tags\": [\"synapse\"] }\n\n// Bad: 10 tags (noise)\n{ \"tags\": [\"synapse\", \"deployment\", \"docker\", \"vps1\", \"2026\", \"june\", \"ssh\", \"git\", \"main\", \"production\"] }\n```\n\n### 규칙 2: 소문자, 하이픈\n\n```\n✅ ci-cd, api-key, mind-key\n❌ CI-CD, APIKey, MindKey\n```\n\n### 규칙 3: 일관된 어휘 사용\n\n태깅 어휘를 설정하고 고수하십시오:\n\n```\n# Project vocabulary\nsynapse, synapse-mcp, synapse-chat\n\n# NOT: synapse_project, synapseProject, SYNAPSE\n```\n\n### 규칙 4: 검색 의도로 태그\n\n\"이 메모리를 어떻게 검색할 것인가?\"라고 자문하십시오.\n\n```json\n// Storing a deployment decision\n{\n \"content\": \"Decided to use Docker Swarm for Synapse deployment\",\n \"tags\": [\"synapse\", \"deployment\", \"docker\", \"swarm\", \"decision\"]\n}\n\n// You'll likely search: ?q=docker+swarm or ?tag=deployment\n```\n\n## 패턴\n\n### 패턴 1: 프로젝트 + 주제\n\n```json\n{ \"tags\": [\"synapse\", \"deployment\"] }\n{ \"tags\": [\"synapse\", \"auth\"] }\n{ \"tags\": [\"synapse-mcp\", \"tools\"] }\n```\n\n검색: `?tag=synapse` (모든 Synapse 프로젝트 메모리)\n검색: `?tag=synapse&q=deployment` (Synapse의 배포 메모리)\n\n### 패턴 2: 유형 + 도메인\n\n```json\n{ \"tags\": [\"mistake\", \"deployment\"] }\n{ \"tags\": [\"decision\", \"database\"] }\n{ \"tags\": [\"pattern\", \"auth\"] }\n```\n\n검색: `?tag=mistake` (모든 실수)\n검색: `?tag=mistake&q=deployment` (배포 실수)\n\n### 패턴 3: 계층적\n\n프로젝트 내 하위 프로젝트의 경우:\n\n```json\n{ \"tags\": [\"synapse\", \"synapse-docs\", \"markdown\"] }\n{ \"tags\": [\"synapse\", \"synapse-mcp\", \"mcp\"] }\n{ \"tags\": [\"synapse\", \"synapse-admin\", \"ui\"] }\n```\n\n검색: `?tag=synapse` (모든 Synapse)\n검색: `?tag=synapse-docs` (문서 하위 프로젝트만)\n\n### 패턴 4: 상태 추적\n\n```json\n// Active project\n{ \"tags\": [\"synapse\", \"active\"], \"priority\": \"high\" }\n\n// Completed project\n{ \"tags\": [\"synapse-v1\", \"completed\"], \"priority\": \"low\" }\n\n// Blocked\n{ \"tags\": [\"synapse-v2\", \"blocked\"], \"priority\": \"high\" }\n```\n\n## 일반적인 사용 사례\n\n### 프로젝트에 대한 모든 결정 찾기\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/search?q=decision&tag=synapse\"\n```\n\n### 도메인의 모든 실수 찾기\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/search?q=mistake&tag=deployment\"\n```\n\n### 활성 작업 찾기\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/by-tag?tag=active\"\n```\n\n### 기술에 대한 메모리 찾기\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/search?q=postgres+performance&tag=database\"\n```\n\n## 태그 유지 관리\n\n### 주기적 검토\n\n```python\n# Find rarely-used tags (candidates for cleanup)\ntags = requests.get(f\"{URL}/memory/tags\",\n headers={\"Authorization\": f\"Bearer {KEY}\"}).json()\n\nfor tag, count in tags.items():\n if count < 2:\n print(f\"Rare tag: {tag} ({count} memories)\")\n```\n\n### 태그 병합\n\n일관성 없는 태그 (`docker`와 `Docker`)가 있는 경우, 병합:\n\n```python\n# Find all memories with \"Docker\" tag\nmems = requests.get(f\"{URL}/memory/by-tag?tag=Docker\",\n headers={\"Authorization\": f\"Bearer {KEY}\"}).json()\n\n# Update each to use \"docker\" instead\nfor mem in mems[\"results\"]:\n tags = [t.lower() for t in mem[\"tags\"]]\n update_memory(mem[\"id\"], tags=list(set(tags)))\n```\n\n## 모범 사례\n\n> [!TIP]\n> - **어휘를 일찍 설정** — 첫날부터 일관된 태그\n> - **검색 의도로 태그** — 나중에 어떻게 찾을 것인가?\n> - **2-5개 태그가 적정 지점** — 너무 적거나 너무 많으면 안 됨\n> - **소문자 + 하이픈** — `CI/CD`가 아닌 `ci-cd`\n> - **주기적 검토** — 중복 병합, 미사용 제거\n\n## 다음 단계\n\n- [메모리 모범 사례](/docs/guides/memory-best-practices)\n- [FTS5 검색](/docs/concepts/fts5-search)\n- [작업 기반 워크플로우](/docs/llm-cookbook/task-driven-workflow)\n","content_html":"

메모리 태깅 전략

\n

태그는 확장 가능한 메모리 검색의 비결입니다. 이 가이드는 적절한 시기에\n올바른 메모리가 돌아오도록 메모리를 태깅하는 방법을 보여줍니다.

\n

태그가 중요한 이유

\n

태그가 없으면, 평면적인 전문 검색만 있습니다. 태그가 있으면, 구조화된\n탐색이 가능합니다:

\n
# Without tags: search everything\nGET /memory/search?q=docker\n\n# With tags: filter by project + technology\nGET /memory/search?q=deployment&tag=synapse&tag=docker

태그를 통해:

\n\n

태깅 스키마

\n

프로젝트 태그

\n

프로젝트 이름을 태그로 사용:

\n
synapse, synapse-mcp, synapse-chat, synapse-sdk

기술 태그

\n

기술 이름 사용:

\n
docker, kubernetes, postgres, fastify, react, typescript

주제 태그

\n

주제 카테고리 사용:

\n
deployment, ci-cd, auth, database, frontend, backend, security

상태 태그

\n

상태 지표 사용:

\n
active, completed, blocked, deprecated

유형 태그

\n

유형 지표 사용:

\n
decision, mistake, pattern, reference, todo

태깅 규칙

\n

규칙 1: 메모리당 2-5개 태그

\n

태그가 너무 적으면 검색 가능성이 떨어집니다. 너무 많으면 노이즈입니다.

\n
// Good: 3 relevant tags\n{ "tags": ["synapse", "deployment", "docker"] }\n\n// Bad: 1 tag (too narrow)\n{ "tags": ["synapse"] }\n\n// Bad: 10 tags (noise)\n{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }

규칙 2: 소문자, 하이픈

\n
✅ ci-cd, api-key, mind-key\n❌ CI-CD, APIKey, MindKey

규칙 3: 일관된 어휘 사용

\n

태깅 어휘를 설정하고 고수하십시오:

\n
# Project vocabulary\nsynapse, synapse-mcp, synapse-chat\n\n# NOT: synapse_project, synapseProject, SYNAPSE

규칙 4: 검색 의도로 태그

\n

"이 메모리를 어떻게 검색할 것인가?"라고 자문하십시오.

\n
// Storing a deployment decision\n{\n  "content": "Decided to use Docker Swarm for Synapse deployment",\n  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]\n}\n\n// You'll likely search: ?q=docker+swarm or ?tag=deployment

패턴

\n

패턴 1: 프로젝트 + 주제

\n
{ "tags": ["synapse", "deployment"] }\n{ "tags": ["synapse", "auth"] }\n{ "tags": ["synapse-mcp", "tools"] }

검색: ?tag=synapse (모든 Synapse 프로젝트 메모리)\n검색: ?tag=synapse&q=deployment (Synapse의 배포 메모리)

\n

패턴 2: 유형 + 도메인

\n
{ "tags": ["mistake", "deployment"] }\n{ "tags": ["decision", "database"] }\n{ "tags": ["pattern", "auth"] }

검색: ?tag=mistake (모든 실수)\n검색: ?tag=mistake&q=deployment (배포 실수)

\n

패턴 3: 계층적

\n

프로젝트 내 하위 프로젝트의 경우:

\n
{ "tags": ["synapse", "synapse-docs", "markdown"] }\n{ "tags": ["synapse", "synapse-mcp", "mcp"] }\n{ "tags": ["synapse", "synapse-admin", "ui"] }

검색: ?tag=synapse (모든 Synapse)\n검색: ?tag=synapse-docs (문서 하위 프로젝트만)

\n

패턴 4: 상태 추적

\n
// Active project\n{ "tags": ["synapse", "active"], "priority": "high" }\n\n// Completed project\n{ "tags": ["synapse-v1", "completed"], "priority": "low" }\n\n// Blocked\n{ "tags": ["synapse-v2", "blocked"], "priority": "high" }

일반적인 사용 사례

\n

프로젝트에 대한 모든 결정 찾기

\n
curl -H "Authorization: Bearer $KEY" \\\n     ".../memory/search?q=decision&tag=synapse"

도메인의 모든 실수 찾기

\n
curl -H "Authorization: Bearer $KEY" \\\n     ".../memory/search?q=mistake&tag=deployment"

활성 작업 찾기

\n
curl -H "Authorization: Bearer $KEY" \\\n     ".../memory/by-tag?tag=active"

기술에 대한 메모리 찾기

\n
curl -H "Authorization: Bearer $KEY" \\\n     ".../memory/search?q=postgres+performance&tag=database"

태그 유지 관리

\n

주기적 검토

\n
# Find rarely-used tags (candidates for cleanup)\ntags = requests.get(f"{URL}/memory/tags",\n    headers={"Authorization": f"Bearer {KEY}"}).json()\n\nfor tag, count in tags.items():\n    if count < 2:\n        print(f"Rare tag: {tag} ({count} memories)")

태그 병합

\n

일관성 없는 태그 (docker와 Docker)가 있는 경우, 병합:

\n
# Find all memories with "Docker" tag\nmems = requests.get(f"{URL}/memory/by-tag?tag=Docker",\n    headers={"Authorization": f"Bearer {KEY}"}).json()\n\n# Update each to use "docker" instead\nfor mem in mems["results"]:\n    tags = [t.lower() for t in mem["tags"]]\n    update_memory(mem["id"], tags=list(set(tags)))

모범 사례

\n

다음 단계

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