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

Tools alone are not enough. If the model can write memory but never receives memory guidance on the next call, users still experience a forgetful agent. Use memory.getSystemPrompt(basePrompt) or add await memory.getPromptBlock() to your system prompt on every agent call.

The prompt block tells the model how to use MemexAI tools and includes shared memory files plus the user's user/index.md when present. It is the bridge between stored memory and changed behavior.

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.