Memory Tagging Strategy

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

Why Tags Matter

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

# Without tags: search everything
GET /memory/search?q=docker

# With tags: filter by project + technology
GET /memory/search?q=deployment&tag=synapse&tag=docker

Tags enable:

• Fast filtering — GET /memory/by-tag?tag=production
• Scoped search — ?q=auth&tag=project-x
• Grouping — find all "mistake" memories for a project
• Cross-referencing — memories sharing tags are related

Tagging Schema

Project tags

Use project names as tags:

synapse, synapse-mcp, synapse-chat, synapse-sdk

Technology tags

Use technology names:

docker, kubernetes, postgres, fastify, react, typescript

Topic tags

Use topic categories:

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

Status tags

Use status indicators:

active, completed, blocked, deprecated

Type tags

Use type indicators:

decision, mistake, pattern, reference, todo

Tagging Rules

Rule 1: 2-5 tags per memory

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

// Good: 3 relevant tags
{ "tags": ["synapse", "deployment", "docker"] }

// Bad: 1 tag (too narrow)
{ "tags": ["synapse"] }

// Bad: 10 tags (noise)
{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }

Rule 2: Lowercase, hyphenated

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

Rule 3: Use consistent vocabulary

Establish a tagging vocabulary and stick to it:

# Project vocabulary
synapse, synapse-mcp, synapse-chat

# NOT: synapse_project, synapseProject, SYNAPSE

Rule 4: Tag with search intent

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

// Storing a deployment decision
{
  "content": "Decided to use Docker Swarm for Synapse deployment",
  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]
}

// You'll likely search: ?q=docker+swarm or ?tag=deployment

Patterns

Pattern 1: Project + Topic

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

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

Pattern 2: Type + Domain

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

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

Pattern 3: Hierarchical

For sub-projects within a project:

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

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

Pattern 4: Status tracking

// Active project
{ "tags": ["synapse", "active"], "priority": "high" }

// Completed project
{ "tags": ["synapse-v1", "completed"], "priority": "low" }

// Blocked
{ "tags": ["synapse-v2", "blocked"], "priority": "high" }

Common Use Cases

Find all decisions about a project

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

Find all mistakes in a domain

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

Find active work

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

Find memories about a technology

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

Tag Maintenance

Periodic review

# Find rarely-used tags (candidates for cleanup)
tags = requests.get(f"{URL}/memory/tags",
    headers={"Authorization": f"Bearer {KEY}"}).json()

for tag, count in tags.items():
    if count < 2:
        print(f"Rare tag: {tag} ({count} memories)")

Merging tags

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

# Find all memories with "Docker" tag
mems = requests.get(f"{URL}/memory/by-tag?tag=Docker",
    headers={"Authorization": f"Bearer {KEY}"}).json()

# Update each to use "docker" instead
for mem in mems["results"]:
    tags = [t.lower() for t in mem["tags"]]
    update_memory(mem["id"], tags=list(set(tags)))

Best Practices

Next Steps

• Memory Best Practices
• FTS5 Search
• Task-Driven Workflow