Scopes and identity
Scopes and identity
Section titled “Scopes and identity”Every memory in eden-memory is tagged with identity scopes. These scopes decide who can see the memory, which project it belongs to, and how bulk operations like prune or migrate apply. This page explains the four scope fields, their defaults, and how they affect queries.
The four scope fields
Section titled “The four scope fields”| Field | Typical value | Purpose |
|---|---|---|
agent_id |
claude-code-cli, cursor, my-agent |
The client or agent that wrote or is reading the memory. |
user_id |
Your username or email | The human the memory is about. |
org_id |
0d3sa, your-org |
Fleet or organization scope. |
workspace_id |
my-project, repository slug |
Project or workspace scope. |
agent_id and user_id are required for tools that read or write memories. org_id and workspace_id are optional, but strongly recommended for team or multi-project use.
Defaults from the environment
Section titled “Defaults from the environment”If a tool call omits org_id or workspace_id, the MCP server falls back to environment variables:
EDEN_ORG_ID→org_idEDEN_WORKSPACE_ID→workspace_id
This lets a project-scoped Claude Code process automatically tag every memory with the right workspace without you passing it on every call.
How scoping affects recall and search
Section titled “How scoping affects recall and search”When you call eden_recall or eden_search_semantic, eden-memory filters to memories that match the scopes you provide. The more scopes you pass, the narrower the result set.
For example, a recall with only agent_id and user_id returns memories across every workspace you have ever used. Adding workspace_id restricts the results to one project.
The total count returned by eden_health is global and not affected by scoping. It counts every memory in the database, including expired and soft-deleted rows that have not yet been purged.
Empty scopes
Section titled “Empty scopes”Some memories may have empty org_id, workspace_id, agent_id, or user_id. You can target these with the _empty filters in eden_prune:
org_empty: trueworkspace_empty: trueagent_empty: trueuser_empty: true
These are useful when cleaning up records created before you started using fleet-wide scopes.
Scoping in prune and migrate
Section titled “Scoping in prune and migrate”eden_prune and eden_migrate are scope-driven bulk tools.
eden_prunedeletes memories that match the scope filters you pass. Without a scope it can affect every row in the database, so it defaults to dry-run and requiresconfirm: true.eden_migrateremapsorg_idand/orworkspace_idfor all matching memories. It is dry-run by default and can optionally back up the database first. See Migrate a workspace.
Cross-scope recall
Section titled “Cross-scope recall”eden-memory does not silently search across scopes. If you want a memory to be visible to multiple agents or workspaces, store it with broad scopes, or store a separate copy per scope. There is no built-in sharing rule layer beyond the identity fields.
Sync and scopes
Section titled “Sync and scopes”Multi-device sync replicates the raw memory rows, including all four scope fields. After sync, both devices have identical scope values, so recall behaves the same way on each device. See How sync works.