How to design memory scopes for a multi-project setup

You are running two or more projects through one agent. Work from Project A keeps surfacing when you are asking about Project B. Or you want a shared layer of facts that both projects can draw on, but specific context stays isolated by default. Memory scopes are how you solve this. Most operators never configure them explicitly and end up with one flat pool of memories that bleeds across everything. This article covers how to design a scope structure that matches the way you actually work, with concrete patterns for the three most common operator setups.

Every indented block in this article is a command you can paste directly into your OpenClaw chat. Your agent will run it and report back. You do not need to open a terminal, edit any files, or navigate any filesystem.

Design before you build the structure

The mistake most operators make is creating scopes reactively: scope bleed appears, they add a scope, a different bleed appears, they add another, and over time they end up with a tangle of overlapping scopes with no coherent structure. The right approach is to map your work contexts before creating any scopes, then build a structure that fits that map.

Before I set up memory scopes, help me map my work contexts. Based on what you know about how I use you: what distinct work areas do I switch between, what knowledge should be shared across all of them, and what knowledge should stay isolated? Give me a proposed scope structure based on actual usage, not a generic template.

The answer to that question is the concrete starting point for your scope design. If the agent has been running for a while and has accumulated memories, it can often infer your work patterns from what has been stored and how often different topics have come up.

The three scope designs that cover most operator setups

Rather than designing from scratch, most setups fit into one of three patterns. Pick the one that matches your situation and customize from there.

Two scopes. One agent doing one main type of work, with global preferences that should always be available.

• agent:shared: preferences, working style, standing instructions, anything universal
• agent:main: everything related to your primary work

Recall queries both scopes in every session. autoCapture writes to agent:main by default. Memories that are genuinely universal get stored in agent:shared explicitly when captured, either by instruction or by your agent recognizing a clearly cross-cutting preference.

Best for: one operator, one agent, one primary area of focus. Works fine until you start managing genuinely separate projects that should not see each other’s context.

One shared scope plus one scope per active project. This is the design described in the scope bleed article and the right structure for most multi-project operators.

• agent:shared: universal preferences and standing instructions
• project:name-a: all context specific to Project A
• project:name-b: all context specific to Project B
• (more project scopes as needed)

Recall queries the active project scope plus agent:shared. Project memories stay isolated. Global preferences remain available in all project contexts.

Set up Design 2 scope structure for my setup. Create the scope definitions and show me the recall configuration that queries the active project scope plus agent:shared. Show me the autoCapture target for each context before applying anything.

Three layers for operators with a clear domain structure: global preferences, domain-level conventions, and project-level specifics.

• agent:shared: operator-level preferences, always available
• domain:work or domain:client: conventions that apply across all work in a domain
• project:specific-name: facts specific to one project or client

Recall queries all three layers when in a project context. Domain-level conventions are available across all projects in that domain without being globally visible. Project specifics stay isolated.

Best for: freelancers with multiple client types, content creators with distinct verticals, or any operator with a clear work and personal separation where each domain has its own distinct conventions that cut across multiple individual projects within it.

Does my usage pattern justify a three-layer scope design, or would the two-layer design serve me just as well? Based on my work contexts, would the middle domain layer hold distinct knowledge that is not already covered by the shared scope?

Deciding what content goes in each scope

The scope structure only works if the right memories end up in the right scopes. This decision is worth thinking through once rather than improvising it during every session.

The shared scope is for knowledge that should be available in any context regardless of what you are working on. The test: would you want this fact to influence how the agent responds even on a completely different project? If yes, it belongs in the shared scope.

• Communication style preferences (how you like things formatted, how verbose you want responses)
• Working hour preferences and timezone
• Standing instructions that always apply (use local models for heartbeats, never push to git without approval)
• Contact information for services you use across projects
• Personal context the agent needs regardless of task (your background, your tools, your constraints)

Project scopes are for knowledge that is specific to a project, client, or task type. The test: would this fact be irrelevant or potentially confusing if it surfaced in a different project’s context? If yes, it belongs in the project scope.

• Client-specific requirements, terminology, and conventions
• Project-specific decisions and their reasoning
• Technical details about a specific codebase, product, or system
• Key contacts specific to this project
• Work-in-progress notes and intermediate results

List the memories currently in my default or main scope. For each one, tell me whether it belongs in agent:shared or a project scope based on whether it is relevant across all contexts or specific to one. Do not move anything yet.

The session start protocol for multi-scope setups in practice

For scope design to work in practice, each session needs to know which context is active. Without a session start protocol, autoCapture defaults to whatever the config says and the agent has no basis for knowing which project scope to use for the current work.

The simplest session start protocol is one line in the first message of each project session:

We are working on [project name] today. Store new memories to scope project:[slug]. For recalls about this project, query project:[slug] first, then agent:shared. For anything universal that applies across all my work, store to agent:shared.

That instruction at the start of the session sets the active context for the entire conversation. The agent knows where to write and where to read for the duration of the session. No config change needed; no gateway restart; it takes effect immediately.

Write a session start template for each of my active projects. For each project, the template should set the active scope, configure the recall priority order, and include a brief reminder of the key context for that project. Format these as short snippets I can paste at the start of each relevant session.

How your scope structure should evolve over time

A scope design that fits your work today may not fit it six months from now. Projects end, new ones start, the agent’s role shifts. Building in a periodic review prevents scope debt from accumulating.

When a project wraps up, the project scope does not need to be deleted. Archive it: export its memories to a plain text file in your workspace, note the date it was archived, and stop querying it in active sessions. If you ever need to revisit the project, the memories are still there. If the project is definitively over and the memories will never be needed again, you can delete the scope at that point.

Project [name] is wrapping up. Export all memories from scope project:[slug] to workspace/memory-archive/project-[slug]-YYYY-MM-DD.md, then remove this scope from the active recall configuration. I want to preserve the memories as a reference without having them surface in current project sessions.

A project that grows large enough to have distinct sub-contexts may benefit from sub-scopes: project:main-project for shared project context and project:main-project-phase-2 or project:main-project-client-b for specific sub-contexts. Recall can query both the sub-scope and the parent project scope to get the full context hierarchy.

Once a month, review your scope structure against your current workload. Are there scopes for projects that have ended? Are there contexts you are working on that do not have a scope yet? Are memories accumulating in the default scope because you forgot to set the project context at the start of recent sessions?

Run my monthly scope audit. List all scopes and their memory counts. Flag scopes for projects that appear to have ended based on memory age (no new memories in 30 days). Flag contexts I am currently working on that do not have a scope. Check whether any memories landed in the wrong scope in the last month. Give me a recommended cleanup action for each flagged item.

Scope design for multi-vertical content operations in practice

Content creators running a multi-vertical operation have a specific challenge: each topic vertical has its own audience, terminology, tone calibrations, and source preferences. A UAP research article and a personal finance explainer should not share recall context even though both are written by the same operator with the same general style.

The recommended structure for a content operation with three or more topic verticals:

• agent:shared: universal editorial voice, formatting preferences, cross-vertical SEO conventions
• vertical:topic-a: audience context, terminology glossary, source list, tone calibration for this topic
• vertical:topic-b: same structure for the second vertical
• content:pipeline: production-specific memories (article queue state, pipeline decisions, publishing conventions) shared across all verticals

I run a content operation covering multiple topic verticals. Set up a scope structure that keeps each vertical’s audience context, terminology, and source preferences isolated while making my editorial voice and pipeline conventions available across all of them. Show me the scope list and what goes in each one.

The content:pipeline scope is worth noting specifically. Production decisions (how the queue is structured, how articles are staged, how publishing is timed) apply across all verticals but are not preferences in the sense that agent:shared stores preferences. A dedicated pipeline scope keeps operational knowledge separate from editorial voice.

Scope design for client work

Client work has a strict isolation requirement: Client A’s proprietary context, requirements, and preferences absolutely cannot surface in a session for Client B. This is the clearest case for per-client scopes with no shared lookup between client scopes at all.

The recommended structure for a freelancer or agency with multiple active clients:

• agent:shared: operator preferences, billing conventions, communication style
• client:client-a: everything specific to Client A (their terminology, requirements, contacts, project decisions)
• client:client-b: same isolation for Client B
• domain:client-work: general professional conventions that apply across all clients but not in personal contexts (standard deliverable formats, typical project structures, common client questions and answers)

Recall in a client session queries client:client-a, domain:client-work, and agent:shared in that order. It does not query any other client scope. Client B’s context is never visible in Client A’s session.

I work with multiple clients and client information must stay fully isolated. Set up per-client scopes with a shared professional conventions scope and a global preferences scope. Confirm that no client scope will ever appear in the recall results of a different client’s session.

Separating work and personal contexts

For operators who use their agent for both work and personal tasks, a domain-level separation prevents work context from appearing in personal sessions and personal context from surfacing during work.

• agent:shared: preferences and facts that are genuinely universal (timezone, contact info, device names)
• domain:work: all work-related context, clients, projects, professional preferences
• domain:personal: personal tasks, household management, personal projects

The session start instruction specifies which domain is active. A morning session for work tasks queries domain:work plus agent:shared. An evening session for personal tasks queries domain:personal plus agent:shared. Neither domain appears in the other.

I use my agent for both work and personal tasks. Set up a work/personal domain separation. When I am working, only work context should surface in recalls. When I am handling personal tasks, only personal context should surface. Universal preferences like my timezone and contact info should be available in both contexts.

Memory quality within scopes

Getting the scope structure right is step one. Step two is making sure the memories within each scope are high quality. A well-structured scope with vague or duplicate memories produces the same poor recall results as a single unsegmented scope. Scope structure is the container. Memory quality is the content.

A high-quality memory is specific enough to only match relevant queries and rich enough to be useful when it does match. Compare these two ways of storing the same fact:

Vague: “User prefers concise output.”

Specific: “User prefers concise output when summarizing research: one to three sentences per source, no filler text, no attribution unless specifically requested.”

The vague version matches almost any recall query that involves output format. The specific version only matches queries about summarizing research, which is exactly when it should surface.

Review the memories in my shared scope. For any preference memory that is very broad or vague, suggest a more specific version that would only surface in the right context. Do not change anything yet. I want to review the suggestions first.

When autoCapture is running across many sessions, the same fact can be captured multiple times with slightly different wording. Duplicate memories produce redundant recall results and inflate the scope size. A periodic deduplication pass removes them.

Check my agent:shared scope for duplicate or near-duplicate memories. Look for memories that capture the same preference or fact with slightly different wording. List the duplicates so I can review them and confirm which version to keep before deleting the others.

Handing off project context between sessions

Multi-scope setups work best when each session starts with a clear context handoff. At the end of each project session, write a brief summary to the project scope capturing key decisions, current state, and open questions. At the start of the next session, recall that summary to restore context quickly rather than reconstructing it from conversation history.

At the end of this session, write a session summary to scope project:[slug]. Include: what was accomplished today, any decisions made, current state of work in progress, and the next three steps. Format it as a memory I can recall at the start of the next session to quickly resume without going through the whole session history.

This handoff pattern is the memory equivalent of leaving a note for yourself. The session summary memory is the most valuable thing you can store in a project scope because it answers the most common start-of-session question: “where did we leave off?”

Common scope design antipatterns to avoid

These are the patterns that seem reasonable at first but create problems as usage grows. Recognizing them early prevents having to restructure a mature memory system.

Some operators create a new scope for every session: session:2026-03-20, session:2026-03-21. This isolates sessions from each other, which is the wrong unit of isolation. The value of memory is accumulation: the agent should get smarter about a project over time by building on what it learned in previous sessions. Per-session scopes break that accumulation entirely and defeat the purpose of having a memory system at all. Use project-level scopes that persist and accumulate across sessions, not session-level scopes that reset the knowledge base with every new conversation.

The shared scope is for universal facts. When operators are not sure where a memory belongs, they default to agent:shared because it is always accessible. After months of this behavior, agent:shared ends up containing hundreds of project-specific memories that should have been isolated in project scopes. The shared scope becomes the same flat, undifferentiated pool you were trying to escape when you introduced scopes in the first place. When you store a memory and are not sure which scope to use, apply the universal test: would this fact be useful or relevant in a completely different project context? If yes, it belongs in agent:shared. If not, it belongs in the current project scope. When in doubt, project scope is the safer default because it is easier to promote a memory to the shared scope later than to clean noise out of the shared scope after the fact.

A scope named “morning tasks” and a scope named “evening tasks” is not a meaningful distinction for most operators and creates confusion without providing useful isolation. Scopes should reflect genuinely different knowledge contexts, not time-of-day segmentation or fine-grained task categories. The test: would the memories in these two scopes ever need to be isolated from each other, or would it always be fine for them to share a recall pool? If they should share, they belong in the same scope.

A project scope that has been running for a year without any cleanup accumulates stale memories, superseded decisions, and information that was true at the time but is no longer accurate. Stale memories are worse than no memories because they actively mislead recall. A project scope with 50 current, accurate memories is more valuable than one with 200 mixed current and stale memories. Schedule a cleanup pass for each active project scope at least quarterly.

Run a full quality audit on my project scope project:[slug]. List all memories and flag: anything that references a decision that has since been reversed, anything that describes a state that no longer exists, and anything that is vague enough to potentially match unrelated queries. I want to see the flagged items before deleting anything.

Measuring whether your scope design is actually working

A good scope design produces noticeably better recall results than a single default scope. The improvement shows up immediately once the structure is in place and the right memories are in the right buckets. Measuring this confirms the structure is working and tells you if something has drifted.

Run a recall quality test. For the current project context, run a recall for a specific topic relevant to this project. Rate the results: how many of the top five results are genuinely relevant to the query, and how many are noise from irrelevant contexts? If more than one result out of five is irrelevant, the scope isolation is not working correctly.

A well-designed scope structure should produce recall results where three to five out of the top five results are genuinely relevant to the specific query being run. If you are consistently seeing two or more irrelevant results in the top five, something is wrong: either the scope boundaries are not correctly isolating contexts, or the memories within the scope are too vague and match too broadly.

Run the recall quality test at the start of each new project quarter. It takes about five minutes and catches scope drift before it compounds. The test is straightforward: pick three representative queries for your current work context, run recalls for each one, and count the relevant results in the top five for each query. If recall precision has dropped since the last test, investigate whether new memories have been added to the wrong scope in the intervening months, or whether the shared scope has grown too large and is diluting project-specific results.

I want to track recall quality over time. After we complete this quarter’s scope audit, store a memory in agent:shared with the current scope structure, memory counts per scope, and a baseline recall precision score. Next quarter, I will recall this baseline and compare it to the current state to see whether scope quality has improved or degraded.

When to change your scope design

The right time to revisit your scope structure is when your work changes in a way that the current design no longer fits well, not when the design is working correctly. A working scope design should be left alone. These are the signals that a redesign is worth considering.

You took on a new type of work that does not fit existing scopes. If you have been doing solo project work and you start taking on clients, the single-project scope structure needs to become a per-client scope structure. Do not try to force new work into an ill-fitting scope. The friction of working against the structure is a signal that the structure needs to change, not that you need to adapt your workflow to the existing scopes.

Your shared scope is larger than all your project scopes combined. This is the sign that too much is ending up in the shared scope. Audit what is there and push project-specific memories into their correct scopes.

You keep forgetting which scope to specify at session start. If the scope structure is complex enough that you cannot remember it without checking documentation, simplify it. A scope structure you actually use consistently and without friction beats a theoretically optimal one that you forget to apply or that requires checking a document every time you start a session.

Recall precision has dropped across multiple sessions on different projects. A decline in recall quality that is not explained by a single scope issue points to a structural problem. Either too many scopes are being queried in every session and the results are getting diluted, or the shared scope has grown so large that it is pushing down relevant project-specific results in every query.

Is my current scope design still the right fit for my work? Review my scope structure against my current and planned work. Are there contexts I am working in that the current structure does not handle well? Would any of the four redesign signals apply to my current setup?

Common questions

There is no technical limit that causes problems at typical memory volumes. The practical limit is cognitive: if you cannot remember which scope a memory should go to without checking documentation, you have too many scopes. For most operators, three to eight scopes covers everything without becoming hard to manage. If you find yourself with 15 or more scopes, consider whether some of them should be merged into a domain scope that consolidates similar contexts rather than having each one isolated.

Before. Create the scope when the project starts, set it as the active context in your first session, and let memories accumulate in the correct scope from day one. Creating a scope after the project is underway means existing memories are in the wrong scope and need to be migrated, which is extra work that is easily avoided by scoping from the start.

It suggests too much is being classified as universal when it is actually project-specific. A large shared scope creates the same recall quality problem as a single unsegmented scope: the recall has too large a pool to search and surfaces irrelevant results. Review the recent additions to agent:shared and ask whether each one would actually cause problems if it were absent from a different project’s context. If it would not, it belongs in the project scope, not the shared one. The shared scope should stay relatively lean: preferences, standing instructions, and genuinely cross-cutting facts.

Yes, if both agents are configured to read from and write to that scope. This is actually a useful pattern for multi-agent setups where agents need to share a knowledge base: a shared scope that all agents query gives them access to the same pool of accumulated knowledge without needing to replicate it. Each agent can also have its own private scope for context that should not be visible to other agents. The key is being explicit in each agent’s config about which scopes it reads from and writes to.

Not without custom configuration. The memory plugin does not have native context detection. The closest you can get is adding a startup check to your agent prompt: “At the start of each session, check what task or project is being worked on and set the appropriate scope for this session.” The agent can ask clarifying questions or infer from context, but it requires the capability to be explicitly included in the prompt rather than being automatic. For operators who switch contexts frequently, the one-line session start protocol (stating the active project at the top of each session) is a lower-friction solution than attempting automated detection.

Yes, if they genuinely have separate context that should not bleed into each other. Ten scopes is manageable with a consistent naming convention and a session start protocol. The overhead is literally one line at the start of each session specifying which scope is active for that context. The benefit is clean, relevant recall for each project without context noise from the other nine. If managing ten scope names feels unwieldy, group related projects under a domain scope and use sub-project scopes within that domain.

Enough to give the agent useful context at the start of a new session without overwhelming recall results. For a typical project, 20-50 well-written memories is sufficient to cover key decisions, client preferences, technical context, and current state. A project scope with 200 memories is usually carrying stale information that has not been pruned. Run a review when a project scope exceeds 75-100 memories and remove anything that is no longer relevant to active work.

Create per-operator scopes for personal preferences and per-project scopes for shared work. For example: operator:alice, operator:bob for individual preferences, and project:shared-project for memories that both operators need. Each operator’s agent session queries their personal scope plus any shared project scopes they are working on. This structure gives each team member personalized behavior while maintaining shared project context.

Create a task-type scope rather than a project scope. For a weekly newsletter that has been running for two years, task:newsletter holds all the accumulated knowledge about how the newsletter works, what the audience responds to, and what has been covered. Unlike a project scope that eventually gets archived, a task-type scope grows indefinitely as knowledge accumulates about the recurring task. These are often the most valuable scopes in a mature OpenClaw setup.

Memory scope information is stored in the memory plugin’s database file, not in your workspace files. A workspace git export captures your markdown files, config files, and workspace content but not the LanceDB memory database unless you explicitly include the database file location in your backup process. To ensure scope structure and memories survive a backup, add the memory database path to your backup routine alongside the workspace directory. The database is typically at a path like /home/node/.openclaw/memory.db or the path configured in your memory plugin settings.

Add a verification step to your session end routine. Before closing a project session, ask your agent to list all memories written during this session and confirm each one landed in the correct scope. Any that are in the wrong scope get moved before the session ends. This takes about two minutes and keeps scope structure clean as memories accumulate. For sessions where you are making many decisions (the kind that generate many memory writes), the verification step is worth the extra time.

Keep Reading: