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.
- Main User Namespace: By default, memories attach to your primary user identifier or system username.
- 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.
- 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:
{
"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.