How MemexAI Works

The mental model for memory files, tool calls, prompt injection, and later recall.

MemexAI gives an AI agent a small memory surface it can read and update, plus a prompt block that puts stored memory back into the next model call. The memory is stored as scoped files in Postgres, not as a hidden model state or a vector-only blob.

The loop

conversation happens
-> model calls a memory tool
-> MemexAI validates the request
-> virtual paths are translated to physical paths
-> Postgres stores files, revisions, and access logs
-> the next model call includes the MemexAI prompt block
-> a later response searches or reads memory and changes behavior

The agent only sees virtual paths like user/profile.md and shared/policy.md. MemexAI translates those paths before touching the database and enforces isolation in code.

What gets stored

MemexAI stores the durable working set an agent should carry forward:

user preferences
profile facts
commitments
project notes
corrections
decisions
shared guidance and policies

Raw chat transcripts can still live in your app, warehouse, or audit system. MemexAI is for the smaller memory record the agent should actually use later.

Prompt block

Writing to memory is not enough. On the next model call, stored files are not automatically in the context window — MemexAI has to inject them. memory.getSystemPrompt(basePrompt) builds a system prompt that includes tool instructions, all shared/* files, and all user/* files for the current user. Without it, the agent forgets across turns even though the data is in Postgres.

Use memory.getSystemPrompt(basePrompt) or add await memory.getPromptBlock() to your system prompt on every agent call. See Prompt Block for details.

Runtime paths

Most production apps use the containerized service:

app or framework adapter -> MemexAI service -> Postgres

Direct Postgres mode embeds the runtime inside your app:

app -> @memexai/core or memexai Python runtime -> Postgres

Both modes share the same schema, path rules, tools, revisions, and access logs.

What adapters do

Adapters do not change how memory works. They only translate MemexAI tools into the shape a framework expects.

For example:

Vercel AI SDK expects tool objects for generateText or streamText.
OpenAI and Anthropic expect tool definitions plus a way to execute tool calls.
LangChain, LlamaIndex, and CrewAI expect framework-native tool wrappers.

After the adapter receives a tool call, MemexAI still runs the same validation, path translation, SQL, revisions, and access logging.

Most agents should start with memory_remember and memory_context — see Memory Tools for when raw file tools are the better choice.