Scoped memory management for Codex (global, project, hybrid, and per-thread options)

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #17496
• #16799
• #17715
• #17185

Powered by Codex Action

Potential duplicates detected. Please review them and close your issue if it is a duplicate. Memory read path ignores cwd and injects entire global memory_summary.md into initial context for new sessions #17496 Cross-project, cross-session state leak #16799 Project-scoped chat history in the Codex IDE extension #17715 Project-based Chat Separation (Isolated Chat Context per Project) #17185 _Powered by Codex Action_

These issues seems not to be related.

Scoped memory management: we solved this for multi-agent, same patterns apply

The cross-project contamination problem you describe is exactly what we hit in multi-agent deployments at KinthAI (31 agents, shared OpenClaw gateway). Our solution maps directly to Codex's needs:

Three-tier memory scoping:

1. Global scope — facts about the user that apply everywhere: name, timezone, coding style preferences, language preferences. Stored in memory/global/.

1. Project scope — facts specific to one repo: architecture decisions, key abstractions, naming conventions, deployment config. Stored in memory/project/{project_hash}/. This is the critical missing tier.

1. Session scope — ephemeral context for the current task: what files we're editing, what approach we chose, what we tried and rejected. Discarded at session end unless explicitly promoted.

The key design decision: scope inheritance
When querying memory, the system searches: session → project → global, with project-scoped facts overriding global facts when they conflict. Example: global memory says "use tabs", but project memory says "this repo uses 2-space indent" → project wins.

What we found doesn't work:

• Automatic scope inference (guessing whether a memory is global or project-specific): unreliable. Better to have explicit scope declaration at write time, with a default of project-scoped.
• Per-thread scope without project scope: too granular. Threads within the same project share most context. Thread-specific memories that are not project-level are rare enough to not need their own tier.

Scope management UX:

• memory list --scope project — show what this project "knows"
• memory promote {id} --to global — a project-specific insight that should apply everywhere
• memory demote {id} --to project — a global memory that is wrong for this specific project

This is fundamentally the same problem as multi-tenant memory isolation in agent platforms. We wrote about the architecture: Why Character.AI Forgets You — Persistent Memory Architecture

This is one of the most important memory architecture decisions for coding agents. From building a scoped memory system for 31 concurrent agents:

Four-scope hierarchy works in practice:

1. Global — platform conventions, model preferences, coding style rules that apply everywhere
2. Project — repository-specific knowledge (architecture decisions, dependency choices, naming conventions). This is by far the most important scope — ~70% of useful memories are project-scoped
3. Branch/task — ephemeral context for a specific piece of work ("we decided to use approach X for this PR"). Auto-expires when the branch is merged
4. Session — working scratchpad, never persisted beyond the current interaction

Cross-project contamination is a real problem: We've seen agents apply project A's conventions to project B (e.g., using Python patterns in a Go repo because the agent previously worked on a Python project). The fix is strict scope isolation with explicit inheritance: a project scope inherits from global, but global memories never auto-inherit from project scopes.

Importance scoring with time decay: Not all memories deserve equal weight. We use relevance = importance × (0.95 ^ days_since_stored) to automatically deprioritize stale memories. A memory about a library choice made 6 months ago may no longer be relevant if the dependency has since been replaced. The decay rate should be configurable per scope — global memories decay slowly, session memories don't need decay at all.

Memory compaction across scopes: When the total memory size approaches the context window limit, compact lower-priority scopes first. Progressive compaction: full memory → structured summary with entity references preserved verbatim → one-line digest. A project-scoped memory about "use PostgreSQL for the auth service" must preserve that exact entity reference even through aggressive compaction.

Conflict resolution between scopes: When global says "prefer tabs" but project says "use spaces," the more specific scope wins. We resolve conflicts by scope specificity: session > branch > project > global. Log the override so the user can review decisions.

Architecture deep-dive on memory scoping and compaction: https://blog.kinthai.ai/why-character-ai-forgets-you-persistent-memory-architecture

This is a critical feature. Global-only memory creates real problems at scale — we saw this firsthand running 31 agents across multiple projects on a shared gateway.

The contamination problem is worse than it looks: It's not just "project A's conventions leak into project B." In a multi-agent setup, Agent A's memory about a failed approach in Project X can cause Agent B to avoid a perfectly valid approach in Project Y. The agents develop learned helplessness from memories that don't apply to their current context.

Our scoping model (four levels, similar to what you're proposing):

1. Global: Platform-wide facts (model capabilities, API rate limits, common patterns)
2. Namespace: Organization/team-level conventions and constraints
3. Project: Repository-specific architecture decisions, file structure, coding patterns
4. Session: Ephemeral working state that shouldn't persist

Key design decisions:

• Resolution order: Session > Project > Namespace > Global (most specific wins)
• Explicit override markers: A project memory can explicitly override a global memory (e.g., "this repo uses tabs, not the org-wide spaces convention")
• Memory isolation at delegation: When an agent in Project A delegates to a helper, the helper inherits only Global + the parent's session context — never the parent's project memories. This prevents the contamination you described.

Per-thread / no-carryover mode: We implement this as a "session-only" scope where memories are written to an ephemeral store that's garbage-collected when the session ends. Useful for exploratory tasks where you don't want experimental approaches polluting the persistent store.

The hybrid mode gotcha: When project and global memories conflict, you need a deterministic resolution strategy. We use importance scoring with scope weighting — project memories get a 2x importance multiplier over global memories, so they naturally win in retrieval ranking.

More on the memory architecture (including the importance scoring, time decay, and compaction that makes scoped memory manageable): https://blog.kinthai.ai/why-character-ai-forgets-you-persistent-memory-architecture

Multi-tenant isolation patterns that prevent cross-project contamination at the infrastructure level: https://blog.kinthai.ai/openclaw-multi-tenancy-why-vm-per-user-doesnt-scale

Scope control is the right thing to ask for, but I'd push on the framing a little. The cross-project contamination you're describing isn't really caused by memory being global. It's caused by not being able to tell, later, where a given memory came from and whether you ever actually meant for it to stick. Scope boundaries help, but on their own they just move the contamination around instead of removing it.

The case that breaks pure scoping is the hybrid one you mention. Once project memory and global memory both feed retrieval, "project takes priority" sounds clean until two entries genuinely conflict, or until something that started as a one-off in one repo quietly gets treated as a general preference. At that point what you want isn't a bigger precedence table, it's knowing which entries you confirmed versus which ones got written automatically, so the confirmed ones can win regardless of scope.

The promote/move-between-scopes controls have the same issue. Moving a memory from project to global is exactly the moment it's most likely to be wrong, so that's the moment that benefits most from a deliberate confirmation step rather than a silent reclassification.

We've spent a while building memory that's split into global and project scopes, and the scoping itself turned out to be the straightforward part. The thing that actually made retrieval safer across repos was attaching provenance to each entry and keeping a human in the loop before anything became a durable, cross-project fact. I'd treat namespacing as the floor here, not the feature.

A concrete workflow where project/repository-scoped memory would be especially valuable:

I work with many independent, long-lived repositories and intentionally create a new Codex thread for every development task. This keeps tasks focused and avoids relying on increasingly long thread context.

The downside is that every new thread has to rebuild the same repository context: architecture, CI/CD structure, build and test commands, conventions, prior design decisions, terminology, and known limitations.

Global memory is not suitable for this because these facts belong to the repository, not to the user, and must not leak into unrelated repositories.

The useful hierarchy would be:

Global user preferences → Repository/workspace memory → Task thread

Important controls would include inspect/edit/delete, provenance for each entry, explicit confirmation before promoting repository knowledge to global scope, and protection for secrets and ignored files.

This would eliminate the current trade-off between one oversized thread that retains repository knowledge and clean task-specific threads that repeatedly rebuild it.