Skip to main content

Use project memory

Project memory keeps the conversations of your project and learns from them. Your agents and your apps then use what it learned.

Fig. 1 · How memory learns from your calls
Chat calls of your appskept when memory is on
Conversationsstored for search, no model call
Memoriesfacts, decisions, procedures, and a knowledge page
Used byyour agents over MCP or the API, and your apps with recall
You use memory fromWithTo
The consoleYour sign-inTurn memory on in Memory settings (Configure), review and pin memories in Memory (Watch), erase an end user in Memory settings
An MCP client, such as Claude CodeYour sign-inLet an agent read and save memories. See Connect an MCP client
Your codeA virtual keyRead, save and erase memories with the /v1/memory API
Each chat callA virtual keyAdd the matching memories to the call with a header

1. Memory is on for every project​

Memory is on for every project that has not turned it off. Memory needs every prompt and answer, so while it is on, Proxium stores every call, and you cannot narrow Stored prompts and answers.

To change memory:

  1. In the console, open Memory in the Configure run of the strip.
  2. Optional: set Memory to off. Proxium saves it at once.
  3. Optional: in Only these senders, type the apps to remember, separated by commas. Empty means every app.
  4. Optional: in Delete conversations after, type a number of days. Empty keeps every conversation and memory, which is the default.
  5. Optional: in Batch of and At least every, set when Proxium learns. See When Proxium learns. With a value in Delete conversations after, At least every must be shorter than it.
  6. Select Save.

Any member of the project can do this. An agent over MCP does the same with proxium_read_memory_settings and proxium_set_memory_settings, as the person who signed in. An admin of Proxium can change the memory of any project with PUT /provision/teams/{project}/memory. Memory settings (Configure) holds the switch, the retention and the erase. The Memory screen (Watch) shows the Knowledge page, the Memories and the Recent conversations.

If you turn memory off, Stored prompts and answers stays at all. To store less, change What to store in Settings › Stored prompts and answers. How long they are kept is a separate setting there: see Data handling.

What Proxium remembers​

Proxium remembers a call when all of these are true:

ConditionExample
The route is /v1/chat/completions, /v1/messages or /v1/responsesNot /v1/embeddings
The call succeededA 503 upstream_failed is not remembered
The app is in Only these senders, or that field is emptyx-proxium-source: support-bot
The call does not send x-proxium-memory: off

A call without x-proxium-source is remembered only when Only these senders is empty.

When a conversation has no new turn for a while, Proxium reads it. It stores the text for search. The first user message becomes the title, without the tags that a tool puts in front of it. This step makes no model call. When the extraction later reads the conversation, it replaces the title with the task of the conversation and adds a short summary.

Proxium reads the user and assistant messages, and the tool calls of the assistant: the name of the tool and its arguments. So a plan or a task that an agent creates with a tool goes into memory. Proxium does not read system prompts.

Tool results​

The output of a tool often holds the lesson of a session, for example the error that showed that a command failed. The setting tool_results of the project says where that output goes:

ValueSearch finds itThe extraction reads it
search (the default)YesNo
extractYesYes
offNoNo

With search, proxium_search_memory and the search route find a word that only a tool result holds, and the batch spends no tokens on it. No memory comes from it, so a recall does not return it. With extract, the batch reads the tool results too, and each batch costs more tokens. Proxium keeps the start of each tool result, up to tool_result_chars characters (default 2,000, from 200 to 20,000). A tool result does not count as a new message for the batch. Change both on Memory settings (Configure), with the MCP tool proxium_set_memory_settings, or with PUT /api/teams/{project}/memory and the fields tool_results and tool_result_chars. A field that the call leaves out keeps its value, and the setting applies to the conversations that Proxium reads after the change.

Decisions​

A decision is a fact with an area and a date. Proxium keeps a decision until a later decision of the same area closes it. The newest decision of an area is the one that holds. proxium_list_decisions reads the live decisions of the project, newest first, with the date, the author and the area of each one. Pass area to read one area, such as database. Each page reads limit decisions, 1 to 100 and 20 by default, and the cursor of the answer reads the next page. The tool posts its body to POST /v1/memory/decisions, and the decisions appear in the Memories list of the Memory screen.

Which conversations Proxium learns from​

Every remembered conversation is stored for search. Proxium writes memories from a conversation only in these cases:

The conversationProxium writes memories
Has more than one turn: a person who chats, or an agent that works in stepsYes
Has an end user (a subject)Yes
Has a call with x-proxium-memory: writeYes
You asked Proxium to remember it. See Ask Proxium to remember a conversationYes
Is one call with no end user and no header, such as a job of a pipelineNo. It is stored for search only

A pipeline job, such as "draft a reply" or "score this text", is one call. Memories from it are seldom read, and each extraction is a model call. So Proxium skips it, unless the job sends x-proxium-memory: write.

When Proxium learns​

Fig. 2 · what memory does, and when
  1. Your app sends a call through Proxium to the vendor. Proxium stores the call in the conversation of the end user. This step makes no model call.
  2. When a conversation has no new turn for a while, Proxium reads it and stores the text for search. This step makes no model call.
  3. When enough new messages wait, or the oldest waited long enough, a batch starts. It makes one model call for each end user with new messages, and writes the memories. A memory that repeats a stored memory word for word is skipped with no model call.
  4. A later call that sends x-proxium-memory: recall gets the matching memories at the end of its last user message. This adds one embedding to the call.

Proxium finds the memories in batches, for each project. A batch starts when one of these is true:

ConditionField on Memory settings
Enough new messages waitBatch of
The oldest new message waited long enoughAt least every
One conversation is quiet and holds enough messagesExtract one idle conversation at

A batch makes one model call for each end user with new messages, and one for the calls with no end user. Each call reads only the messages since the last batch. The cost follows the amount of text that Proxium learns from, not the number of batches.

The third rule is off by default. Extract one idle conversation at turns it on. One conversation then needs no new turn for the idle time of the project, and at least that many messages. The next pass extracts it. A quiet project learns a short conversation in minutes, not after a day. 0 or null turns the rule off again. The API stores both as null, so a project that turns the rule off is in the same state as one that never set it. The field is idle_extract_messages, from 1 to 100000: set it on Memory settings, with the MCP tool proxium_set_memory_settings, or with PUT /api/teams/{project}/memory. proxium_read_memory_settings returns it, and returns null while the rule is off.

Check whether a conversation reached its goal​

The goal check reads an idle conversation and the memories of the project. A model then judges whether the person reached the goal. Proxium adds one row for each model that answered the conversation, with that model's share of the answered calls.

The check is off by default, because it spends the money of the project. Turn it on with Goal check on Memory settings, with the MCP tool proxium_set_memory_settings, or with PUT /api/teams/{project}/memory. The field is goal_check.

SettingFieldDefault
The share of the conversations that the check readsgoal_check_share_pct100
The most USD of the project that one day can spendgoal_check_daily_usd0.25
The credit of a conversation that several models answeredgoal_creditweighted
The model that judgesgoal_judgeauto

goal_credit takes weighted, last or solo. weighted gives each model its share of the answered calls. last gives the credit only to the model of the last answer. solo counts only the conversations that one model answered.

goal_judge picks the judge. auto tries the endpoint of the project first and the Jev of the platform grant after it. The platform judge reads its model from the environment variable GOAL_JEV_MODEL of the deployment, so the pin of the chart holds that variable as platformClassifier.goalModel. A rollout without it stops the check with circuit_open on the endpoint of the project.

goal_judge takes auto, own_key or platform. auto asks the endpoint of your project first, then the model of the platform. The platform hop runs only when the team granted platform_goal_jev. own_key never spends on the platform. platform always uses the platform's model, and the team must grant platform_goal_jev first. An operator gives that grant in Settings › Platform access › Jev for the goal check, or with the MCP tool proxium_set_platform_access.

A conversation with no goal is not judged. The check skips a conversation with an open secret finding, and it retries a failed call at most three times. A call that never reached a model does not use one of the three attempts: the check waits one backoff and asks again. An attempts count older than one hour starts again from one, because the reason for the failure had time to go. The check does not change the conversation that it reads. A share under 20 judged conversations is not a number yet: the check waits, and says how many it has. Set the daily cap to 0 to stop the check.

The Vendor scorecard on Performance shows the share in the column Goal reached. A cell reads 63% of 48 when 30 of 48 judged conversations reached the goal. A tooltip names the unclear band and the share of the conversations that this model answered alone.

The batch uses the models of the tier memory-extract. The default is glm-5.3-flash at reasoning low, then gemma4:31b. To use your own models, set the tier memory-extract on Routing.

The Memory settings screen shows how many new messages wait, and the latest time of the next batch. If a batch fails, the screen shows the error. Proxium tries again later, with longer waits, and the messages wait until a batch succeeds.

Standing facts in every call​

Some facts hold for every request of a project: the decisions the team agreed on, and the memories a person pinned. Proxium puts them in one small block that a recalled call always gets, whatever its request says:

Standing items of this project and its repository; apply them to every request:

  • the deploy window is Tuesday at 02:00 UTC. (id …)
  • Related to the request: …

The block holds three sections. Standing items comes first: the live decisions and the pinned memories, most important first. Then About the user holds the memories of the end user. Then Related to the request holds the memories that match the words of the request. A decision stands in the block even when it shares no word with the request. An agent does not need to search for a fact that it was already told.

Two writers fill the standing section. A hook writes while the session works: an agent records a decision with proxium_record_decision, or with POST /api/teams/{project}/memory/decisions. A person pins a memory on the Memory screen or with the API. Compaction writes too. When a long conversation is compacted, Proxium records the decisions of the compacted part. A fact that the summary replaces then stands again as a decision.

Proxium closes a decision when a later decision of the same area, scope and subject replaces it. The project then holds one live answer per question. The closed decision stays in the history with its date and the id of the decision that replaced it. proxium_list_decisions shows only the live ones. A person's decision is never closed this way: only a person closes or unpins a person's fact.

The block goes at the end of the last user message. Proxium stores it for the turn, so every call of one turn reads the same block. While the standing items do not change, the standing part is byte for byte the same across calls with different requests. The prompt cache of the vendor then keeps serving the prefix. The standing section has a budget of AXON_MEMORY_STANDING_CHARS characters, 1,200 by default. Proxium keeps the pinned memories and the best decisions within it.

2. Choose what each call does​

Send the x-proxium-memory header on a call:

ValueWhat Proxium does
No headerRemembers the call. Proxium learns from it by the rules in Which conversations Proxium learns from. When the project's recall switch is on, it also adds the matching memories, as recall does
writeRemembers the call, and Proxium learns from its conversation, even when it is one call with no end user
recallRemembers the call, and first adds the matching memories to it. Only on chat and Messages calls
offDoes not remember the call

Example: a support bot that knows the earlier tickets of the user.

Terminal
curl https://proxium.tech/v1/chat/completions \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-H "x-proxium-source: support-bot" \
-H "x-proxium-memory: recall" \
-H "x-proxium-memory-subject: user-ana" \
-d "{\"model\": \"$PROXIUM_MODEL\", \"messages\": [{\"role\": \"user\", \"content\": \"Which plan am I on?\"}]}"

With recall, Proxium searches the memories for the last user message. It adds the best matches at the end of the last user message, in <proxium-memory> tags. The messages before it stay the same, so the vendor's prompt cache still serves them. The calls that follow the same user message, such as the tool calls of an agent, get the same memories. If the search is slow or fails, the call continues without memories.

On /v1/responses, recall acts as write. Any other value gets 400 invalid_memory_mode.

The block starts with "Recalled by Proxium from the project memory, not written by the user. Each line has its memory id." Each memory is one line: its text, then its id. A person or an agent can give the id to proxium_correct_memory or proxium_rate_memory.

The request trace shows the step Recalled memory. It says why the call recalled: the header, the project setting or the classifier. It also gives the number of lines and their size. GET /api/teams/{slug}/requests/{id}/trace returns the same in memory.

Standing facts first​

The block holds the standing facts of the project before the matched memories. The standing facts are the memories that a person pinned and the live decisions of the project. They apply to every request, so the block carries them on every call of the project, not only when they match. They hold up to 1,200 characters; the setting AXON_MEMORY_STANDING_CHARS of the gateway changes this, and 0 turns them off.

The standing part stays byte-identical on every call of one user message. The same text goes to the model for the follow-up calls, so the vendor prompt cache still serves them.

A newer fact closes the older one​

Proxium compares a new fact with the live facts of the same subject and statement. When the two state the same thing, Proxium closes the older statement. The older memory keeps its id and points to the newer one (superseded_by). The recall returns the newer one only. A person can still read the closed memory in the Memory screen.

A memory that a person wrote or pinned is closed only by a person. An agent never closes it.

Give every call of a project its memories​

An app that sends no x-proxium-memory header never reads the memories that Proxium learns from it. To change this with no change in the app, turn on Calls with no x-proxium-memory header: recall on Memory settings. An agent can do the same with proxium_set_memory_settings and recall: true. The API field is recall of PUT /api/teams/{slug}/memory. It is off for a project that saved no setting.

The switch is for the whole project. Every app of the project pays for a recall: up to 1.5 seconds and 2,000 characters by default (AXON_MEMORY_RECALL_TIMEOUT_MS, AXON_MEMORY_RECALL_CHARS). A call that sends write or off keeps that mode.

Memory can be on while no call read a memory in 14 days and extraction cost money in that time. Then the Memory settings screen and proxium_read_memory_settings say so. Extraction goes on until you turn on recall or turn memory off. With no project, the tool answers every project that you are a member of, and one block names each project.

A scope is the name of one repository or one folder. Write it in lower case: the engine folds a name to lower case, so Axon and axon are one scope. A name with a path in it takes its last segment: ~/code/example is the scope example. A blank name is no scope, and no scope means the whole project.

Keep the repositories of a project apart​

One project can serve many repositories. Without a scope, an agent in one repository gets the memories of all of them.

Send the name of the repository in the header x-proxium-memory-scope on a call. On the MCP server, pass scope with the name, or add ?scope=<repository> to the MCP URL.

A recall, a search and a wake-up then return the memories of that repository and the memories of the whole project. A memory with no scope belongs to the whole project.

Proxium gives a new memory the scope of the conversation it learned from: the scope header of the call names it. When a call carries no scope, the memory worker asks the model for the repository that a statement holds for. The worker checks the name and stores the statement with that scope. A scope that the conversation carries always wins over the answer of the model. A save can name its scope: proxium_save_memory writes the scope that you pass, and it names the scope in its answer. A project with one scope uses that scope when the call names none. A project with more than one scope refuses a save that names none, and the answer lists the names to choose. A name that the project does not know starts a new scope. The save sets new_scope for it, and the tool does that for you when you pass the name.

The scope unsorted marks a memory that Proxium could not place. No recall returns it. To place it, call proxium_correct_memory with its scope, or move the row in the console.

proxium_list_scopes answers the scopes of a project with the number of memories in each one. It gives one row for each name and one row of null for the whole project. It also gives one row named unsorted for the memories that recall leaves out. With no project it reads every project that you are a member of, and each row names its project. Use it before a save when you do not know the name. GET /api/teams/{slug}/memory/scopes and GET /v1/memory/scopes return the same rows.

Which project a read covers​

A person can belong to many projects. A memory read over MCP then covers every project of the person, and the answer names the project of each hit. To read one project, pass its slug in project. To read one repository of it, pass scope. This rule covers proxium_recall_memory, proxium_search_memory, proxium_search_prompts, proxium_list_conversations, proxium_read_conversation, proxium_memory_item, proxium_resume_memory, proxium_project_context, proxium_weekly_digest and the other read tools of the memory.

A read that spans projects gives the newest rows of each project in one answer. A read by id skips a project that does not hold the id. A paged list returns no cursor when it spans projects, because each project has its own page. Name one project to page through it.

A write over MCP needs one project when the person belongs to more than one. Pass the slug in project, and the answer names the project that it changed. A memory of an app goes to the project of its key or of its route. A virtual key belongs to one project, so every call of the key reads and writes that project only.

3. Name the end user​

A memory can be about one end user of your app. Proxium calls that end user the subject. It reads the subject from:

  1. The x-proxium-memory-subject header.
  2. If there is no header, the user field of the body. On /v1/messages, metadata.user_id.
CallReads the memories of
With subject user-anauser-ana, and the memories of the whole project
Without a subjectThe whole project, and the memories of every end user
warning

Send the subject on each recall call that is about one end user. Without it, the call can get the memories of other end users.

Use an opaque id, not an email address. A subject has at most 256 characters, and no control characters. Else a remembered call gets 400 invalid_memory_subject.

4. Give your agents the memory​

An agent reads the memory over MCP, and your own code uses the /v1/memory API with a virtual key. Give your agents the memory has the tools, the wake-up, the save, the notebook and the secret scan.

The record-decision hook​

A decision of a session is worth the memory only when the agent saves it. With the Claude Code plugin, put a decision of the session on one line that starts with Decision: . At the end of the session, the record-decision hook reads the transcript. When no memory holds the decision, the hook asks the agent once. It tells the agent to save the decision with proxium_save_memory, kind decision, with the reason in the same statement. The hook saves nothing itself and never blocks a session: it is silent on any failure. It needs jq.

Review what agents saved​

Open the Memory screen. The Memories list shows to review first: the memories of agents that no person confirmed. For each one, select Confirm, Pin, Edit or Remove. To add a memory yourself, fill in New memory, Kind and User, and select Save. The MCP tool proxium_memory_status and GET /v1/memory/status answer these counts, with the conversations that are behind the batch.

Erase one end user​

warning

You cannot undo an erasure.

With the API, with any virtual key of the project
Terminal
curl -X DELETE https://proxium.tech/v1/memory/subjects/user-ana \
-H "Authorization: Bearer $PROXIUM_KEY"
In the console, as an owner of the project
  1. Open Memory in Configure. The section Erase one user is at the bottom of the screen.
  2. Type the subject in User id.
  3. Select Erase permanently, and confirm.

Proxium deletes the memories, the profile and the conversations of the subject, in one transaction. It also deletes the stored prompts and answers of every call that named that subject, whether memory kept the call or not. The audit record keeps a SHA-256 hash of the subject. Data handling says what stays.

Delete old conversations​

By default, Proxium keeps every conversation and memory. To delete old conversations, type a number of days in Delete conversations after on Memory settings. Once a day, Proxium then deletes the conversations whose last turn is older than that. It also deletes the memories that were corrected or removed before that time. Live memories stay. A conversation that memory has not read yet stays until memory reads it. The deletion runs with memory on or off.

What memory costs​

The memories, the pages and the embeddings come from model calls. Reading a conversation makes none. Proxium sends them through the routing of your project, and records them as your spend. Your usage names the job of each call: proxium-memory:extract, proxium-memory:merge, proxium-memory:graph, proxium-memory:pairs, proxium-memory:page, proxium-memory:label, proxium-memory:goal or proxium-memory:embed. The goal check spends as proxium-memory:goal, and the daily cap (goal_check_daily_usd) counts the calls of that day. The top of the Memory settings screen shows the memory cost of this month, which adds up every job. An agent reads the same numbers with proxium_memory_spend. It answers the cost of the last 30 days at most, against the 30 days before it, split by model and by job.

Proxium uses the first tier of each row that has a model your project can call. A model of Proxium's own vendors counts only when your project uses Proxium's models. A model of your own vendors always counts.

JobTiers, in order
Memories from the conversations, in batchesmemory-extract, then trivial
Merges, graph facts and pagesmemory-consolidate, then memory-extract, then trivial
Embeddingsmemory-embed, then embed

To set a chain for a tier, see Route requests to models.

The Memory settings screen and the MCP tool proxium_read_memory_settings name the tier and the first model of each job. When no tier of a row has a model that your project can call, they say so. Memory then runs no batch until you set memory-extract or trivial. Without an embedding model, recall matches words only.

To search what a person typed, the files that agents changed and similar conversations, see Search past conversations.