{"title":"Memory Tagging Strategy","slug":"memory-tagging-strategy","category":"llm-cookbook","summary":"How to tag memories for effective search and filtering — the tagging system that scales.","audience":["llm"],"tags":["cookbook","tagging","memory","strategy"],"difficulty":"intermediate","updated":"2026-06-27","word_count":347,"read_minutes":2,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Memory Tagging Strategy\n\nTags are the secret to scalable memory retrieval. This guide shows how to tag\nmemories so the right ones come back at the right time.\n\n## Why Tags Matter\n\nWithout tags, you have flat full-text search. With tags, you have structured\nnavigation:\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\nTags enable:\n\n- **Fast filtering** — `GET /memory/by-tag?tag=production`\n- **Scoped search** — `?q=auth&tag=project-x`\n- **Grouping** — find all \"mistake\" memories for a project\n- **Cross-referencing** — memories sharing tags are related\n\n## Tagging Schema\n\n### Project tags\n\nUse project names as tags:\n\n```\nsynapse, synapse-mcp, synapse-chat, synapse-sdk\n```\n\n### Technology tags\n\nUse technology names:\n\n```\ndocker, kubernetes, postgres, fastify, react, typescript\n```\n\n### Topic tags\n\nUse topic categories:\n\n```\ndeployment, ci-cd, auth, database, frontend, backend, security\n```\n\n### Status tags\n\nUse status indicators:\n\n```\nactive, completed, blocked, deprecated\n```\n\n### Type tags\n\nUse type indicators:\n\n```\ndecision, mistake, pattern, reference, todo\n```\n\n## Tagging Rules\n\n### Rule 1: 2-5 tags per memory\n\nToo few tags = poor discoverability. Too many = noise.\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### Rule 2: Lowercase, hyphenated\n\n```\n✅ ci-cd, api-key, mind-key\n❌ CI-CD, APIKey, MindKey\n```\n\n### Rule 3: Use consistent vocabulary\n\nEstablish a tagging vocabulary and stick to it:\n\n```\n# Project vocabulary\nsynapse, synapse-mcp, synapse-chat\n\n# NOT: synapse_project, synapseProject, SYNAPSE\n```\n\n### Rule 4: Tag with search intent\n\nAsk: \"How will I search for this memory?\"\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## Patterns\n\n### Pattern 1: Project + Topic\n\n```json\n{ \"tags\": [\"synapse\", \"deployment\"] }\n{ \"tags\": [\"synapse\", \"auth\"] }\n{ \"tags\": [\"synapse-mcp\", \"tools\"] }\n```\n\nSearch: `?tag=synapse` (all Synapse project memories)\nSearch: `?tag=synapse&q=deployment` (deployment memories in Synapse)\n\n### Pattern 2: Type + Domain\n\n```json\n{ \"tags\": [\"mistake\", \"deployment\"] }\n{ \"tags\": [\"decision\", \"database\"] }\n{ \"tags\": [\"pattern\", \"auth\"] }\n```\n\nSearch: `?tag=mistake` (all mistakes)\nSearch: `?tag=mistake&q=deployment` (deployment mistakes)\n\n### Pattern 3: Hierarchical\n\nFor sub-projects within a project:\n\n```json\n{ \"tags\": [\"synapse\", \"synapse-docs\", \"markdown\"] }\n{ \"tags\": [\"synapse\", \"synapse-mcp\", \"mcp\"] }\n{ \"tags\": [\"synapse\", \"synapse-admin\", \"ui\"] }\n```\n\nSearch: `?tag=synapse` (all Synapse)\nSearch: `?tag=synapse-docs` (just docs sub-project)\n\n### Pattern 4: Status tracking\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## Common Use Cases\n\n### Find all decisions about a project\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/search?q=decision&tag=synapse\"\n```\n\n### Find all mistakes in a domain\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/search?q=mistake&tag=deployment\"\n```\n\n### Find active work\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/by-tag?tag=active\"\n```\n\n### Find memories about a technology\n\n```bash\ncurl -H \"Authorization: Bearer $KEY\" \\\n \".../memory/search?q=postgres+performance&tag=database\"\n```\n\n## Tag Maintenance\n\n### Periodic review\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### Merging tags\n\nIf you have inconsistent tags (`docker` and `Docker`), merge them:\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## Best Practices\n\n> [!TIP]\n> - **Establish vocabulary early** — consistent tags from day 1\n> - **Tag for search intent** — how will you find this later?\n> - **2-5 tags is the sweet spot** — too few or too many is bad\n> - **Lowercase + hyphens** — `ci-cd` not `CI/CD`\n> - **Review periodically** — merge duplicates, remove unused\n\n## Next Steps\n\n- [Memory Best Practices](/docs/guides/memory-best-practices)\n- [FTS5 Search](/docs/concepts/fts5-search)\n- [Task-Driven Workflow](/docs/llm-cookbook/task-driven-workflow)\n","content_html":"

Memory Tagging Strategy

\n

Tags are the secret to scalable memory retrieval. This guide shows how to tag\nmemories so the right ones come back at the right time.

\n

Why Tags Matter

\n

Without tags, you have flat full-text search. With tags, you have structured\nnavigation:

\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

Tags enable:

\n\n

Tagging Schema

\n

Project tags

\n

Use project names as tags:

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

Technology tags

\n

Use technology names:

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

Topic tags

\n

Use topic categories:

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

Status tags

\n

Use status indicators:

\n
active, completed, blocked, deprecated

Type tags

\n

Use type indicators:

\n
decision, mistake, pattern, reference, todo

Tagging Rules

\n

Rule 1: 2-5 tags per memory

\n

Too few tags = poor discoverability. Too many = noise.

\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"] }

Rule 2: Lowercase, hyphenated

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

Rule 3: Use consistent vocabulary

\n

Establish a tagging vocabulary and stick to it:

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

Rule 4: Tag with search intent

\n

Ask: "How will I search for this memory?"

\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

Patterns

\n

Pattern 1: Project + Topic

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

Search: ?tag=synapse (all Synapse project memories)\nSearch: ?tag=synapse&q=deployment (deployment memories in Synapse)

\n

Pattern 2: Type + Domain

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

Search: ?tag=mistake (all mistakes)\nSearch: ?tag=mistake&q=deployment (deployment mistakes)

\n

Pattern 3: Hierarchical

\n

For sub-projects within a project:

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

Search: ?tag=synapse (all Synapse)\nSearch: ?tag=synapse-docs (just docs sub-project)

\n

Pattern 4: Status tracking

\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" }

Common Use Cases

\n

Find all decisions about a project

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

Find all mistakes in a domain

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

Find active work

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

Find memories about a technology

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

Tag Maintenance

\n

Periodic review

\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)")

Merging tags

\n

If you have inconsistent tags (docker and Docker), merge them:

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

Best Practices

\n

Next Steps

\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"]}