---
title: "Organizing User Memories"
description: "Organizing and partitioning your memories ensures that your AI assistants and coding tools recall relevant context without mixing up distinct projects, personal preferences, or sub-agent tasks. By ..."
last_updated: "2026-10-11T17:38:36.505607+00:00"
canonical_url: "https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/how-to-guides/organizing-user-memories"
---

## Overview

### Introduction

Organizing and partitioning your memories ensures that your AI assistants and coding tools recall relevant context without mixing up distinct projects, personal preferences, or sub-agent tasks. By leveraging identifiers such as user scopes, project tags, and custom categories, you can precisely control where memories are stored and retrieved.

> [!NOTE]
> Proper organization prevents unrelated project details from polluting your global profile while allowing shared preferences to remain accessible across different coding environments.

---

### Core Concepts

Understanding how memories are categorized and partitioned helps you structure your data effectively:

* **Scopes**: Define the boundary of a memory. You can store information at the project level (specific to the current repository), session level (ephemeral to a single run), or global level (user-wide across all projects).
* **Identifiers (`user_id`, `agent_id`, `run_id`)**: Parameters used to namespace your data. Entity identifiers partition memories so that different users, specific sub-agents, or automated runs do not overwrite each other.
* **Coding Categories**: Predefined classifications for technical knowledge, architectural decisions, workflows, problems, and fixes that help structure what the agent learns about a codebase.

---

### Tagging and Partitioning Across Users and Sub-Agents

Memories are automatically partitioned based on the active session context, but you can explicitly target specific namespaces using tool parameters or configuration settings.

1. **Main User Namespace**: By default, memories attach to your primary user identifier or system username.
2. **Sub-Agent Isolation**: Sessions running under sub-agents automatically namespace their data using session routing keys, ensuring that ephemeral sub-agent tasks do not clutter your main history.
3. **Explicit Scoping**: When adding or searching for memories via tools, you can specify a write scope:
   * `"project"` (default): Scoped to the current repository or application.
   * `"session"`: Scoped strictly to the active run.
   * `"global"`: User-wide across all projects and repositories.

---

### Customizing Memory Categories

Projects can automatically bootstrap custom categories to organize technical knowledge effectively. The standard coding memory categories include:

| Category Name | Description |
| :--- | :--- |
| `project_knowledge` | What the project is and how its code, APIs, data, files, and components work. |
| `decisions_and_constraints` | Why an approach was chosen, what must remain true, and rules future work must follow. |
| `workflows` | How to run, test, debug, deploy, configure, or otherwise work on the project. |
| `problems_and_fixes` | Bugs, failures, known pitfalls, their causes, and how to fix or avoid them. |
| `results` | Outcomes and measurements from tests, benchmarks, experiments, or investigations. |

---

### Example: Adding a Scoped Memory

When adding a memory through an agent tool, you can pass specific parameters to control its scope and categorization:

```json
{
  "text": "User switched from almond milk to oat milk lattes after developing an almond sensitivity",
  "scope": "project",
  "metadata": {
    "category": "preference",
    "confidence": 0.9
  }
}
```

> [!TIP]
> Use the `"global"` scope sparingly and only when saving universal user preferences (such as preferred coding languages or communication styles) that apply across every repository.

## Related

- [Managing Memories](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/core-features/managing-memories)
- [Searching Memories](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/guide/core-features/searching-memories)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/faa36707-7c28-4f69-a18f-700ff61c704e/llms.txt) for all pages in this wiki.