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.

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.