Give your agents the memory
This page continues Use project memory. Memory reads and writes need the memory of the project turned on, and a key or a sign-in that may change it.
The loop is on for an agent by default
An agent that works until a condition is true runs as a loop. Proxium counts every
conversation of a project that set nothing, and it refuses nothing, because every ceiling of
that project is 0. A conversation enters the loop when it sends x-proxium-conversation with
one stable id, and a project turns the loop off with the setting enabled = false.
The "done" of the agent does not end the loop. The stop check reads the answer against the
goal of the conversation. While an item is missing, the answer carries
x-proxium-stop-check: not_reached: <the item that is not in the answer>. The goal state then
reads not_met, and the agent continues the work. The header value starts with the word of the
verdict (met, not_reached or not_checked), then a colon and the reason of the check. Read Loops for the goal, the judge and the
ceilings, and install the skill proxium-loop for the agent.
The verification contract
Six rules hold for every loop, and desk holds the same six rules on munhq/desk#211. Proxium and desk therefore work alone, and they work together.
- The agent does not grade its own work. A verifier outside the agent decides that a goal is met.
- The goal is held out. Proxium writes the stop condition when the loop starts, and the verifier reads that copy only. A later condition from the agent waits for a person.
- The checker is independent. The verifier is of another family than the worker by default, and the setting
verifier=any_vendorallows one family. The verifier reads the goal and the evidence, and no transcript. - The goal cannot get weaker in silence. Proxium counts each change of the stop condition and each refused "done", and the Loops screen shows both.
- The checker is measured. A daily job asks the verifier again on the settled items, and the score of each model is on the Loops screen and in
proxium_read_verifier_score. - Proxium works alone. With desk present, Proxium reads the "Done when" lines of the linked desk issue as the stop condition. It reports the stall and continues a run only when desk asks.
| Part | Proxium alone | desk alone | Both present: owner of the part |
|---|---|---|---|
| The goal | The stop condition of a conversation (#578) | The "Done when" lines with typed verifiers (munhq/desk#204) | desk |
| The verdict | The verifier of #578 with the goal check of #548 | The desk loop | desk; the goal score of Proxium is evidence for a judge line |
| Held-out goal (rule 2) | #589, step 1 | munhq/desk#206 | desk |
| Independent checker (rule 3) | #578, step 2 of #589 | munhq/desk#206 | The product that runs the check |
| Weaker goal (rule 4) | #589, step 3 | munhq/desk#206 part 2 | Proxium for the conversation; desk for code and checks |
| Measured checker (rule 5) | #589, step 4 | munhq/desk#207 | Each product for its own verifier |
| The live guard of a run | #576 | The desk loop counts respawns and cost | Proxium |
| Continue or restart a run | The runner of #578 | The desk loop | desk |
An agent with an MCP client uses the MCP server, with a person's sign-in or with a key of the project. Your own code uses the memory API with a virtual key, at https://proxium.tech/v1:
| Task | Request | Reference |
|---|---|---|
| Read the memory at the start of a task | POST /v1/memory/wake-up | Wake-up |
| Search memories, decisions, conversations, diary and values | POST /v1/memory/search | Search |
| Read one conversation | GET /v1/memory/episodes/{id} | Episode |
| Save a memory | POST /v1/memory/items | Remember |
| Ask Proxium to remember a conversation | POST /v1/memory/episodes/{id}/remember | Remember a conversation |
| Correct a memory | PATCH /v1/memory/items/{id} | Correct |
| Rate a memory | POST /v1/memory/items/{id}/rating | Rate |
| Remove a memory | DELETE /v1/memory/items/{id} | Forget |
| Read the knowledge graph, in the order of time too | POST /v1/memory/graph, POST /v1/memory/graph/timeline | Graph, Timeline |
| End one relation of the graph | POST /v1/memory/graph/invalidate | Graph invalidate |
| List the live decisions of one area | POST /v1/memory/decisions | Decisions |
Start a task with wake-up
The answer holds the pinned and trusted memories, the titles of the newest conversations and the knowledge page. A subject adds the memories of that end user.
curl https://proxium.tech/v1/memory/wake-up \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-d '{"subject": "user-ana"}'
Save a memory
Save one statement in each memory. kind is fact (default), preference, decision, event, procedure or open_item. importance says how much a memory counts. Leave out subject for a memory of the whole project.
curl https://proxium.tech/v1/memory/items \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Large refunds need a second approval.", "kind": "procedure"}'
Keep the open items of a loop
A loop of an agent saves the work that is still open as open_item before it stops. The resume
answer returns the live open items first, newest first, at most 20, so the next iteration starts
with them. An item from a checker names its type at the start of its text: test, deploy, check,
docs or judge. Remove an item when its work is done, and no later resume returns it.
curl https://proxium.tech/v1/memory/items \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "test: the resume test of #577", "kind": "open_item"}'
Which memory wins
A newer memory replaces an older memory that says something else. The older memory stays in the history, and no recall returns it again. Its superseded_by column names the newer memory. Each day the consolidation also compares the new memories of every origin with the memories near them. When a memory replaces an older one, the older memory gets one more wrong_count. A memory of origin human is never closed this way.
A decision also carries an area. The area is the question that the decision answers. Use auth, database, payments, api, frontend, deploy, testing, observability, security, pricing, licensing, positioning, or another short label of the project. A new decision of the same area closes the older decision of the same area, scope and end user. So a project keeps one live answer for each question.
A decision of one area does not close a decision of another area. Proxium never closes a memory that a person wrote in this way: only a person removes a person's memory. The area is at most 64 characters. Proxium trims it and writes it in lower case.
To read the decisions that stand, list them. The list goes newest first. area keeps one question. The answer names next_cursor, and the next call sends it as cursor. A page holds 20 decisions, and limit gives 1 to 100.
curl "https://proxium.tech/v1/memory/decisions?area=database&limit=2" \
-H "Authorization: Bearer $PROXIUM_KEY"
curl https://proxium.tech/v1/memory/decisions \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-d '{"decision": "Use Postgres for the orders", "reason": "the team runs it already", "area": "database"}'
Ask Proxium to remember a conversation
Save a memory when you know the statement. When a whole conversation matters, ask Proxium to read it and write the memories. Proxium reads it with its memory model at its next tick, within about half a minute. It does not wait for the conversation to go idle. Get the id of the conversation from search or wake-up. Proxium reads the conversation from its start. focus is optional: it says what to look for.
curl https://proxium.tech/v1/memory/episodes/$CONVERSATION_ID/remember \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-d '{"focus": "the plan and the tasks"}'
Proxium answers 202. An agent over MCP uses the tool proxium_remember_conversation. Add now: true to read the conversation in the call: its answer then holds memories, the count that the read wrote.
Rate a memory after you use it
curl https://proxium.tech/v1/memory/items/$MEMORY_ID/rating \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-d '{"rating": "useful"}'
A memory rated wrong two times leaves the recall, until a person selects Confirm on the Memory screen.
Keep a notebook over MCP
An agent that connects over MCP has more tools to keep its notebook. They help it to continue earlier work. They need memory on. A person signs in with a browser. A key of the project does the same work without a sign-in, and a key gets these tools too. See One key for each agent.
| Tool | What it keeps |
|---|---|
proxium_resume_memory | Reads the newest conversations, the newest decisions with their reasons and the newest diary entries |
proxium_record_decision | Saves a decision and its reason as one memory of kind decision; the area makes a later decision of the same area close it |
proxium_write_diary and proxium_read_diary | Keep the entries that an agent writes about its own work, one stream for each agent name |
proxium_set_value and proxium_get_value | Keep a value by namespace and key, for example the branch of a task |
proxium_add_relation, proxium_kg_timeline and proxium_kg_stats | Write one relation of the knowledge graph: a thing, a predicate and another thing. Read the facts in the order they became true, and keep the ones that ended with their valid_to. Count the facts, the names and the relation types |
proxium_kg_invalidate | Ends one relation of the knowledge graph on the day it stopped, and keeps the other relations of its memory live |
proxium_exclude_path | Names a directory or a file that memory does not read. From the next call, a message that names the path writes no chunk and no extraction reads it. A path is absolute, at most 512 characters, and a project names at most 50. The call needs confirm: true, and the answer says added: false when the path was already there. The Memory screen shows the same list |
A diary entry and a stored value are not memories. No recall returns them. The search returns them, and the read tools of the notebook return them too.
Search the diary and the values
proxium_search_memory reads all five stores in one call. It answers one ranked list, and the first hit of each store ranks above every later hit. Each hit names its store in source: memory, decision, conversation, diary or value.
The parameter sources chooses the stores, for example ["diary", "values"]. Without it, the search reads all five. An unknown name fails the call, and the message names the name that Proxium refused. The diary and the values match words only, on the read replica. A word must appear in full or as the start of a longer word. A value matches on its key and on its value.
A relation is a memory of kind fact. When you correct or remove the memory, the relation closes with it.
Proxium screens each text of the notebook like a memory. It refuses a prompt injection and replaces a credential with a placeholder.
What a virtual key may change
| Action | Allowed | If not |
|---|---|---|
| Save a memory | When memory is on | 409 memory_off |
| Pin a memory | Never. Only a person can pin, in the console | 403 forbidden |
| Correct or remove a memory of an agent | Yes | |
| Correct or remove a memory that a person wrote | No | 403 forbidden |
A text has a size limit. Proxium refuses a text that looks like a prompt injection (403), and it replaces a credential in the text with a placeholder. A correction keeps the old memory in the history.
Find a secret in the stored prompts
When memory writes a chunk, it finds the secrets in that text and keeps one finding for each one. A finding holds the detector, the rule, the message, the window and a preview, never the secret. proxium_security_summary, proxium_security_session, proxium_security_dismiss and proxium_security_rules answer the findings. A dismissal covers every finding with the same preview. Sensitive data scanning says what the scan looks for.