Memory Scopes

MemexAI uses a two-level path namespace. Every path an agent sees is a virtual path. The system translates it to a physical path in the database before SQL runs.

`user/`

Virtual paths starting with user/ belong to the user whose userId is in the tool context.

user/profile.md
user/notes/session-2026-05.md
user/reminders.md

When an agent writes user/profile.md for user_123, MemexAI stores it as:

users/user_123/profile.md

The agent never sees the physical path.

userId is a partition key, not necessarily a person. Most deployments pass a human user ID, but it can be a background agent ID, a tenant ID, a workspace ID, or any stable application identity. The system enforces isolation by that key regardless of what it represents.

// Human user
memex.forUser({ userId: "user_alice_123", actor: "assistant" })

// Background agent with its own private workspace
memex.forUser({ userId: "agent_research_bot_v2", actor: "agent" })

// Tenant-scoped deployment
memex.forUser({ userId: "tenant_acme_prod", actor: "assistant" })

Multi-agent patterns

Pattern A — Per-agent private memory

Pass the agent's ID as userId. The agent gets a private user/ namespace with no special setup:

const agentMemex = memex.forUser({ userId: "agent_research_bot_v2", actor: "agent" })
await agentMemex.execute("memory_write", {
  path: "user/scratchpad.md",
  content: "Research notes…",
})
// Stored as: users/agent_research_bot_v2/scratchpad.md

Pattern B — Shared memory for a trusted single-tenant team

This is not tenant isolation. When shared writable mode is on, all agents can write anywhere under shared/. There is no per-path RBAC. Do not use this if untrusted agents can write, or if you need hard isolation between orgs. Named mounts will be the RBAC-correct solution when available.

For a single trusted deployment where agents share team-level context, use deep paths under shared/ with MEMEX_SHARED_WRITE_MODE=rw:

MEMEX_SHARED_WRITE_MODE=rw

await memex.execute("memory_write", {
  path: "shared/teams/marketing/q4-brief.md",
  content: "…",
})

# Filter admin view by prefix
memex-admin files list --prefix shared/teams/marketing/

`shared/`

Virtual paths starting with shared/ are visible to every user. By default they cannot be written by agents.

shared/index.md
shared/policy.md
shared/faq.md

Use shared files for context your agents should always have access to: policies, reference docs, product facts, project canon, style guides, learned procedures, or team guidance.

Operators can opt into collective shared memory:

MEMEX_SHARED_WRITE_MODE=rw

When this is enabled, memory_write and memory_patch can target shared/**, and the prompt block/tool descriptions tell the agent that shared memory is writable. This is useful when a team wants shared project memory to improve over time from real usage: canon, policies, style rules, procedures, and cross-user insights can be patched once and benefit every later user.

Use it only for durable global knowledge. Keep private user facts, secrets, raw transcripts, and untrusted external content out of shared/**.

Blocked paths

MemexAI rejects:

Physical paths like users/someone/profile.md.
Paths with .., //, or backslashes.
Writes to shared/ when shared writable mode is disabled.

Path isolation is enforced in code, not left to the model prompt.

Why only two scopes

MemexAI ships with two scopes because most products only need these two trust levels: per-user private and operator-global. Adding more scopes before knowing the shape of real usage would bake in premature assumptions.

Team, workspace, and project scopes are on the roadmap as named mounts — register additional memory scopes at init time so a team agent can write to team/itinerary.md and user/prefs.md in the same call. The current design deliberately avoids those scopes until the pull is real.

Vocabulary

For definitions of user, agent, operator, virtual path, physical path, and other terms used across these docs, see Design Principles — Vocabulary.

user/