{"title":"Memory Best Practices","slug":"memory-best-practices","category":"guides","summary":"How to structure memories for effective recall — categories, keys, tags, priorities.","audience":["human","llm"],"tags":["guide","memory","best-practices","patterns"],"difficulty":"intermediate","updated":"2026-06-27","word_count":605,"read_minutes":3,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# Memory Best Practices\n\nHow you structure memories determines how useful they are. This guide covers\npatterns for categorizing, tagging, and prioritizing memories so the LLM can\nrecall the right information at the right time.\n\n## Categories: Pick the Most Specific\n\n| Category | Use For | Example |\n|----------|---------|---------|\n| `identity` | User name, role, contact info | `\"user_name\": \"Michael Schäfer\"` |\n| `preference` | Likes, dislikes, working style | `\"communication\": \"Prefers concise responses\"` |\n| `fact` | Verifiable facts | `\"office_location\": \"Berlin, Germany\"` |\n| `project` | Project status, decisions | `\"project_synapse\": \"v1.5.0 deployed\"` |\n| `skill` | User's skills | `\"skill_python\": \"Advanced, 10+ years\"` |\n| `mistake` | Past errors to avoid | `\"mistake_npm_version\": \"Always bump version\"` |\n| `context` | Session-relevant context | `\"current_focus\": \"Working on docs system\"` |\n| `note` | Misc notes | `\"note_idea\": \"Try Redis for caching\"` |\n\n> [!TIP]\n> When in doubt, use `fact` for verifiable info and `note` for everything else.\n> Don't over-categorize — better to have a clear `fact` than a confusing `context`.\n\n## Keys: Meaningful Identifiers\n\nThe `key` field is the memory's identifier. Use meaningful, stable keys:\n\n**Good keys:**\n- `user_name`\n- `project_synapse_status`\n- `preference_communication_style`\n- `mistake_npm_version_bump`\n\n**Bad keys:**\n- `mem_001` (not meaningful)\n- `temp` (not descriptive)\n- `2026-06-27-note` (date doesn't help recall)\n\n### Key naming conventions\n\n- `snake_case` (lowercase with underscores)\n- Prefix with category: `preference_*`, `project_*`, `mistake_*`\n- Use descriptive nouns, not verbs\n- Keep under 50 characters\n\n## Tags: For Search and Filtering\n\nTags enable fast filtering and search. Add 2-5 tags per memory:\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### Tag patterns\n\n- **Project names**: `synapse`, `synapse-mcp`, `synapse-chat`\n- **Topics**: `deployment`, `ci`, `database`, `auth`\n- **Status**: `active`, `completed`, `blocked`\n- **Priority indicators**: `urgent`, `long-term`\n\n> [!NOTE]\n> Tags are case-insensitive. Use lowercase for consistency.\n\n## Priorities: Be Realistic\n\n| Priority | Use For | % of Memories |\n|----------|---------|---------------|\n| `critical` | User identity, legal info, irreversible decisions | ~5% |\n| `high` | Active projects, important preferences | ~20% |\n| `normal` | Most facts, notes, context | ~65% |\n| `low` | Ephemeral, nice-to-know | ~10% |\n\n> [!WARNING]\n> Don't mark everything `critical`. If everything is critical, nothing is.\n> Reserve `critical` for things that would cause real harm if forgotten.\n\n## When to Store vs Not Store\n\n### Always store\n\n- User identity (name, email, role)\n- Long-term preferences\n- Project decisions and rationale\n- Past mistakes and lessons learned\n- Commitments made to the user\n\n### Don't store\n\n- Transient state (use variables instead)\n- Verbatim conversation history (chat system handles this)\n- Sensitive data (passwords, API keys)\n- Easily derivable facts (current date, file contents)\n- Ephemeral context (use `context` category with low priority)\n\n## Updating Memories\n\nPOST `/memory` with the same `category` + `key` updates the existing memory:\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> Use stable keys so you can update without creating duplicates. The LLM\n> should re-POST the same key as info changes, not create new memories.\n\n## Memory Lifecycle\n\n```\nCreate → Active → Stale → Archive → Delete\n```\n\n- **Create**: POST /memory with full context\n- **Active**: Recall frequently, update as needed\n- **Stale**: Still relevant but not actively used (lower priority?)\n- **Archive**: Set priority to `low`, keep for historical reference\n- **Delete**: DELETE /memory/:id when no longer relevant\n\n### Periodic cleanup\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## Pattern: Memory Inheritance\n\nFor hierarchical context (project → subproject → task):\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\nThe LLM can then search `q=synapse+docs` to find all related memories.\n\n## Pattern: Decision Log\n\nStore decisions with rationale so the LLM doesn't re-litigate them:\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## Pattern: Mistake Avoidance\n\nStore mistakes with specific avoidance instructions:\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## Anti-Patterns to Avoid\n\n> [!WARNING]\n> - **Storing conversation logs** — chat system handles this\n> - **Storing entire files** — use script store or external storage\n> - **Storing ephemeral state** — use variables\n> - **Storing secrets** — use environment variables\n> - **Duplicating memories** — use stable keys\n> - **Over-tagging** — 2-5 tags per memory is ideal\n> - **Everything is critical** — be realistic with priorities\n\n## Next Steps\n\n- [Memory API](/docs/api/memory)\n- [Persistent LLM Agent](/docs/guides/persistent-llm-agent)\n- [Memory Tagging Strategy](/docs/llm-cookbook/memory-tagging-strategy)\n","content_html":"

Memory Best Practices

\n

How you structure memories determines how useful they are. This guide covers\npatterns for categorizing, tagging, and prioritizing memories so the LLM can\nrecall the right information at the right time.

\n

Categories: Pick the Most Specific

\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
CategoryUse ForExample
identityUser name, role, contact info"user_name": "Michael Schäfer"
preferenceLikes, dislikes, working style"communication": "Prefers concise responses"
factVerifiable facts"office_location": "Berlin, Germany"
projectProject status, decisions"project_synapse": "v1.5.0 deployed"
skillUser's skills"skill_python": "Advanced, 10+ years"
mistakePast errors to avoid"mistake_npm_version": "Always bump version"
contextSession-relevant context"current_focus": "Working on docs system"
noteMisc notes"note_idea": "Try Redis for caching"
\n
When in doubt, use `fact` for verifiable info and `note` for everything else.\nDon't over-categorize — better to have a clear `fact` than a confusing `context`.

Keys: Meaningful Identifiers

\n

The key field is the memory's identifier. Use meaningful, stable keys:

\n

Good keys:

\n\n

Bad keys:

\n\n

Key naming conventions

\n\n

Tags: For Search and Filtering

\n

Tags enable fast filtering and search. Add 2-5 tags per memory:

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

Tag patterns

\n\n
Tags are case-insensitive. Use lowercase for consistency.

Priorities: Be Realistic

\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
PriorityUse For% of Memories
criticalUser identity, legal info, irreversible decisions~5%
highActive projects, important preferences~20%
normalMost facts, notes, context~65%
lowEphemeral, nice-to-know~10%
\n
Don't mark everything `critical`. If everything is critical, nothing is.\nReserve `critical` for things that would cause real harm if forgotten.

When to Store vs Not Store

\n

Always store

\n\n

Don't store

\n\n

Updating Memories

\n

POST /memory with the same category + key updates the existing memory:

\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")
Use stable keys so you can update without creating duplicates. The LLM\nshould re-POST the same key as info changes, not create new memories.

Memory Lifecycle

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

Periodic cleanup

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

Pattern: Memory Inheritance

\n

For hierarchical context (project → subproject → task):

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

The LLM can then search q=synapse+docs to find all related memories.

\n

Pattern: Decision Log

\n

Store decisions with rationale so the LLM doesn't re-litigate them:

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

Pattern: Mistake Avoidance

\n

Store mistakes with specific avoidance instructions:

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

Anti-Patterns to Avoid

\n

Next Steps

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