How your agent uses memory
Your agent follows one loop: search before it answers, record after it learns. The plugin’s hooks keep it on the loop, so the memory grows on its own as you work.
Search first
Section titled “Search first”Before it answers a question about the project, the agent calls semantic_search. It searches the narrowest scope first and widens when nothing fits:
| Scope | Searches | Use it for |
|---|---|---|
session |
this line of work | the most relevant, the default start |
workspace |
every session of the project | decisions made elsewhere in the project |
global |
every workspace you can reach | patterns across projects |
When nothing is found, it explores the code as usual, and then records what it found, so the next session does not have to.
Record after
Section titled “Record after”After a change, a fix or an answer worth keeping, the agent calls update_conversation_context with a typed record: a decision_made with its rationale, a problem_solved with the cause and the fix, a code_change with what changed. Each record names the entities it touches and how they relate. The record types are on the Concepts page.
Records that replace an old fact name it in supersedes: the old one ends and stays in the history.
How search ranks
Section titled “How search ranks”Search matches the query by meaning, by words and through the graph, fuses the rankings, and returns each hit with the records just before and after it in its session, so the agent sees the context of a decision, not only the line that matched.
mode sets how much work goes into the order: fast, local or accurate; a call that names none gets the server’s default. What each one adds, how exact it is and how long it takes, measured: Search.
accurate sends the query and the text of the best candidates to Voyage only in a workspace that turned it on, and a search over several workspaces only when every one of them has. Every search answer says whether a reranker ordered it (reranked), and only those count as reranker calls on your plan.
Fresh or timeless
Section titled “Fresh or timeless”recency_bias favors newer results. Leave it at 0 for decisions and architecture that stay true; raise it when you look for something recent:
| Looking for | recency_bias |
|---|---|
| architecture, conventions | 0 (default) |
| a recent fix | 0.3 to 0.7 |
| a bug from this week | 0.5 to 1.0 |
date_from and date_to cut by date instead, and author keeps one writer’s records.
The conversation
Section titled “The conversation”With capture on (pcx setup --capture), each prompt and final answer is kept beside the records. Search them with sources: "messages", or both with sources: "all". What it is for and how long it is kept: Conversations.
When it forgets
Section titled “When it forgets”The agent does not use the memory tools. Check that the plugin is installed and that the first prompt of a session shows the post-cortex banner. A client without hooks needs the loop in its instructions file.
Results from another project show up. The session is attached to the wrong workspace, or the search used global. Pin the project with pcx setup --project, and search with scope: "workspace".
Old answers win over new ones. Record the new fact with supersedes naming the old record, so the old one ends. For a quick fix, search with recency_bias: 0.5.