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 but 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, or team guidance.

Blocked paths

MemexAI rejects:

• Physical paths like users/someone/profile.md.
• Paths with .., //, or backslashes.
• Writes to shared/.

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.