feature: support role-scoped memory spaces with inheritance

[MatrixAdventurer]

Summary

Introduce role-scoped memory spaces with inheritance so clients can create a role like writer based on main, instead of encoding role semantics in raw memory content.

Problem

Today, if clients want different agents or workflows to share a common memory base while keeping role-specific rules separate, the usual workarounds are awkward:

• put role labels in raw content (for example [role:writer])
• use separate user IDs per role
• use branches/snapshots for role separation

These options are all imperfect:

• raw content tags are not first-class structure
• separate user IDs fragment shared user memory
• branches/snapshots are better for rollback, experiments, and version control than for steady-state collaboration

Why role-scoped memory is different from branches

This proposal treats branch/snapshot and role as different concepts:

• Branch / snapshot → version control, rollback, experimentation, recovery from mistakes
• Role → collaboration, inherited shared memory, role-specific overlays

In other words:

• branch answers "which version?"
• role answers "which collaborator / viewpoint?"

Proposed model

Support a first-class scope model such as:

• main (shared base memory space)
• writer based on main
• reviewer based on main
• github-ops based on main

A role would inherit base memories from main, and only store its own delta.

Example

create role "writer" based on main

Then a writer-oriented recall would effectively retrieve:

• shared memories from main
• role-local memories from writer

without copying all shared memories into a second store.

Minimum capability set

Scope management

• create role based on a parent scope
• list roles/scopes
• delete role
• inspect role parent

Store / recall

• store memory into a scope
• recall within main only
• recall within writer as main + writer
• optionally recall role-only or parent-only

Governance / introspection

• stats per scope
• diff role vs parent
• snapshot / rollback a role scope independently

Possible implementation directions

Option A: first-class scope fields

Store scope as structured metadata, for example:

• scope_kind
• scope_value
• parent_scope

This is more extensible than a single role field because it can later support:

• role
• project
• session
• other inherited overlays

Option B: role as a specialized memory space abstraction

Model role as a named inherited memory space directly in the API/CLI and map it internally onto scope metadata.

Why this matters

This would make Memoria a better substrate for multi-agent systems where:

• one base memory should be shared
• collaborators should have their own stable operating rules
• role-specific recall should not pollute or fork the entire user memory graph

This seems especially useful for agent setups like:

• writer / reviewer
• planner / executor
• github-ops / coding-agent

Non-goal

This proposal is not trying to replace branches/snapshots. Those should continue to serve rollback and versioning.

The goal is to add a separate abstraction for collaboration-oriented inherited scopes.

[MatrixAdventurer]

Additional design direction after thinking through real agent usage in OpenClaw-style setups:

This feature would be even more valuable if it is not limited to "separate memories by role", but also supports role-aware retrieval and workspace identity / operating-context integration.

What seems important

1. Role/scope should affect retrieval, not just storage

It is not enough to store memories with role/scope metadata if retrieval still behaves like a flat search.

In practice, retrieval should know things like:

• current controller identity
• active role (Writer, Reviewer, GitHub Ops, etc.)
• inherited/shared base scope (main)
• role-local overlay

So the real need is closer to:

• role-aware memory retrieval
• scope inheritance during recall
• role-local delta over shared base memory

2. Workspace context should participate too

For agent systems, memory does not live alone. There is usually also workspace-defined context such as:

• SOUL.md -> identity / persona
• AGENTS.md -> operating rules / constraints
• roles/*.md -> role definitions

When retrieving memory, it would be very useful if the system could integrate or align with those layers, rather than treating memory as an isolated store.

Not necessarily by dumping whole files into memory verbatim, but by allowing the retrieval/model layer to understand:

• who the agent is
• what role it is currently acting in
• what operating rules apply
• what inherited scope should be consulted

3. Why this matters

Without this, a multi-role agent setup can easily mix contexts incorrectly.
For example:

• Reviewer retrieves Writer-specific working memory without distinction
• controller/global memories and role-local memories get blended too early
• role definitions in workspace files are disconnected from actual memory recall

A stronger end-state

A more complete model might be:

• main = shared base memory
• role scopes inherit from main
• retrieval can operate in:
  • base only
  • role + base
  • role only
• retrieval can optionally incorporate workspace identity/rule context derived from SOUL.md, AGENTS.md, and role definitions

So the feature becomes not just "role-scoped storage", but a broader identity-aware / role-aware memory system.

I think that would make this much more useful for real multi-agent orchestration.