Design Principles

MemexAI makes a small number of opinionated decisions that affect everything downstream. Understanding them helps you structure memory well and predict behavior when things are working correctly.

Files, not embeddings

Memory is Markdown text stored as rows in Postgres — not embedding vectors in a separate store.

This means memory is human-readable, grep-able, patchable by a script, and auditable with a SQL query. You can open any memory file in the admin UI and understand exactly what the agent knows. You can also run eval fixtures against a known memory state and get reproducible results.

BM25 and memory-link traversal cover most retrieval cases in practice. When you need semantic recall, optional pgvector hybrid search is available via MEMEX_SEARCH_MODE=auto — see Docker service setup. Both modes are testable and produce predictable results.

Path-enforced isolation

Multi-tenancy is enforced in code, not prompts.

When an agent calls a memory tool, MemexAI validates the virtual path and injects the userId before touching the database. user/profile.md physically becomes users/{userId}/profile.md. Agents cannot construct a path that reaches another user's data, regardless of what the model generates.

Shared memory is read-only for agents by default through the same mechanism. A write to shared/anything.md is rejected at the path validation layer unless the deployment explicitly enables MEMEX_SHARED_WRITE_MODE=rw.

Deterministic retrieval

memory_smart_read returns the same files for the same query on the same data, every time.

Retrieval is BM25 full-text search for initial candidates, followed by forward memory-link traversal within a character budget. Every file in the response carries a reason field — query_match, linked, or recency — explaining how it was found.

This makes retrieval testable. You can write an eval that seeds a known memory state and asserts exactly which files are returned and why.

Memory links keep context connected

Memory links let one durable file point at another without copying the same facts everywhere.

When an agent writes user/profile.md containing [[user/preferences.md]], a later smart read that seeds profile.md can follow the link to include preferences.md in the same response. This keeps hub files and supporting notes connected while preserving an inspectable file model.

Bidirectional backlinks and hub scoring are planned next: notes that point back to a hub file will be able to surface as inbound context, and highly referenced files will be able to rank higher in search.

Writes are permanently recorded

Every write creates a full content snapshot in mx_revision. Nothing is silently overwritten.

Agents can correct memory — a later write can update or contradict an earlier one. But the previous version is always recoverable. The access log records every read and write, including which tool call caused it.

This supports post-hoc debugging: when an agent gives a wrong answer, you can inspect the exact memory state it read and trace every write that produced that state.

Admin and agent have separate trust levels

Agents and operators are not the same thing. MemexAI enforces this structurally.

• Agents authenticate with an API key and can always write to user/*. They can read shared/*, and can write it only when the deployment enables shared writable mode.
• Operators authenticate with an admin secret and can read or write any file, inspect revisions, manage config, and control dreaming behavior.

The boundary is not advisory — it is enforced at the route and path validation level. Changing it requires changing how the service is deployed or extending the path rules in code.

Vocabulary

Related

• Memory scopes
• How MemexAI works
• Shared memory as behavior guide
• Dreaming