Add first-class workspace namespace isolation

[scottgl9]

Summary

Add a first-class workspace namespace boundary that is separate from the existing project field.

Today agentmemory already has useful project scoping and optional AGENT_ID-based isolation, but that is not enough for setups where one agentmemory daemon backs multiple higher-level environments such as work, personal, research, or separate customer/client spaces.

In those setups, project is doing double duty:

• sometimes it means "the top-level workspace boundary"
• sometimes it means "the project identifier inside that workspace"

That ambiguity makes isolation incomplete and fragile.

Problem

A few concrete failure modes show up when a single server is shared across multiple workspaces:

• The same project slug can exist in multiple workspaces.

  • Example: project=project-a in namespace-a
  • Example: project=project-a in namespace-b
  • Today those are not modeled as distinct first-class spaces.

• Query-time project filtering is not the same thing as a true namespace boundary.

  • If callers forget to pass project, legacy/unscoped data can still bleed across boundaries.
  • Some internal paths filter by project, others primarily rely on stored metadata or post-filtering.

• Cached artifacts keyed only by project can collide.

  • Project profiles are the clearest example.
  • Two workspaces using the same project identifier should not share one cached profile.

• A separate top-level workspace boundary is useful even when the same project names, file names, concepts, or lessons appear in multiple places.

Why this matters

For multi-workspace users, especially those separating work vs personal data, isolation should be a first-class property, not just a naming convention or a best-effort filter.

The desired model is:

• namespace = top-level workspace boundary
• project = project identifier within that namespace

Examples:

• namespace=workspace-a, project=project-a
• namespace=workspace-b, project=project-a

Those should coexist without sharing sessions, observations, memories, profiles, or lesson fingerprints unless the caller intentionally opts into a broader scope.

Proposed design

Add:

• AGENTMEMORY_NAMESPACE
• AGENTMEMORY_NAMESPACE_SCOPE=shared|isolated

Behavior:

• Stamp namespace onto write paths such as sessions, observations, memories, lessons, and project profiles.
• In isolated mode, read paths should default to the configured namespace and fail closed unless a caller explicitly opts out.
• Keep project as the intra-namespace identifier.
• Key cached project profiles by namespace + project rather than project alone.

This is deliberately parallel to the existing AGENT_ID + AGENTMEMORY_AGENT_SCOPE pattern, but solving a different problem:

• agentId isolates roles/agents
• namespace isolates workspaces/environments

Scope of the proposed change

Core areas that need namespace awareness:

• write stamping on session/observe/remember/compress paths
• recall and search paths
• context/enrichment paths
• REST list/read endpoints
• cached project-profile storage
• lesson fingerprinting / dedup boundaries
• docs and config examples

Validation expectation

A change like this should include regression coverage for:

• same project name in different namespaces
• search isolation across namespaces
• context/enrich isolation across namespaces
• separate project profiles per namespace
• isolated default behavior with explicit wildcard override

Why not just keep using project?

Because project is still useful and should stay useful inside a workspace.

If project is overloaded to mean both "workspace" and "project inside workspace", then users have to flatten two different identity levels into one string, and internal code has to keep guessing what that string actually represents.

A dedicated namespace layer makes the model clearer and more robust.

Implementation note

I already have a working branch that implements this model and validates it with focused tests plus a clean build. I’m opening a PR linked to this issue next so the concrete patch can be reviewed alongside the design rationale here.