Skip to main content

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.

  1. The agent does not grade its own work. A verifier outside the agent decides that a goal is met.
  2. 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.
  3. The checker is independent. The verifier is of another family than the worker by default, and the setting verifier = any_vendor allows one family. The verifier reads the goal and the evidence, and no transcript.
  4. 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.
  5. 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.
  6. 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.
PartProxium alonedesk aloneBoth present: owner of the part
The goalThe stop condition of a conversation (#578)The "Done when" lines with typed verifiers (munhq/desk#204)desk
The verdictThe verifier of #578 with the goal check of #548The desk loopdesk; the goal score of Proxium is evidence for a judge line
Held-out goal (rule 2)#589, step 1munhq/desk#206desk
Independent checker (rule 3)#578, step 2 of #589munhq/desk#206The product that runs the check
Weaker goal (rule 4)#589, step 3munhq/desk#206 part 2Proxium for the conversation; desk for code and checks
Measured checker (rule 5)#589, step 4munhq/desk#207Each product for its own verifier
The live guard of a run#576The desk loop counts respawns and costProxium
Continue or restart a runThe runner of #578The desk loopdesk

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:

TaskRequestReference
Read the memory at the start of a taskPOST /v1/memory/wake-upWake-up
Search memories, decisions, conversations, diary and valuesPOST /v1/memory/searchSearch
Read one conversationGET /v1/memory/episodes/{id}Episode
Save a memoryPOST /v1/memory/itemsRemember
Ask Proxium to remember a conversationPOST /v1/memory/episodes/{id}/rememberRemember a conversation
Correct a memoryPATCH /v1/memory/items/{id}Correct
Rate a memoryPOST /v1/memory/items/{id}/ratingRate
Remove a memoryDELETE /v1/memory/items/{id}Forget
Read the knowledge graph, in the order of time tooPOST /v1/memory/graph, POST /v1/memory/graph/timelineGraph, Timeline
End one relation of the graphPOST /v1/memory/graph/invalidateGraph invalidate
List the live decisions of one areaPOST /v1/memory/decisionsDecisions

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.

Terminal
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.

Terminal
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.

Terminal
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.

Terminal
curl "https://proxium.tech/v1/memory/decisions?area=database&limit=2" \
-H "Authorization: Bearer $PROXIUM_KEY"
Terminal
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.

Terminal
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​

Terminal
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.

ToolWhat it keeps
proxium_resume_memoryReads the newest conversations, the newest decisions with their reasons and the newest diary entries
proxium_record_decisionSaves 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_diaryKeep the entries that an agent writes about its own work, one stream for each agent name
proxium_set_value and proxium_get_valueKeep a value by namespace and key, for example the branch of a task
proxium_add_relation, proxium_kg_timeline and proxium_kg_statsWrite 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_invalidateEnds one relation of the knowledge graph on the day it stopped, and keeps the other relations of its memory live
proxium_exclude_pathNames 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​

ActionAllowedIf not
Save a memoryWhen memory is on409 memory_off
Pin a memoryNever. Only a person can pin, in the console403 forbidden
Correct or remove a memory of an agentYes
Correct or remove a memory that a person wroteNo403 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.