PowerContext memory operations

PowerContext keeps project memory — decisions, constraints, current state, task outcomes, next steps — in a server-owned artifact family, and returns it with exact citations. This skill covers the five operations an agent needs when a user asks about that memory, or asks to persist it.

The HTTP contract, the response shapes and the status codes were verified against a running Server; see Memory operations for the request and response bodies, and Run a PowerContext Server for how to start one.

Route the request

| Intent / 意图 | Operation | Reference | | --- | --- | --- | | Find a prior decision / 查找历史决策 | search_memory | Memory operations | | Inventory or audit the memory / 盘点、审计记忆 | list_memory_entries | Memory operations | | Save a conclusion / 记住一条结论 | remember_memory | Memory operations | | Bounded context for one turn / 本轮上下文 | prepare_context | Memory operations | | Hand work to another session / 交接、接续工作 | prepare_context, then carry the returned carrier | Memory operations |

Do not call PowerContext for ordinary coding, for a question the current context already answers, or to restate facts supplied in the request. An empty result is a normal answer, not a failure — report it as "no matching memory", and never invent an entry to fill the gap.

1. Resolve the Scope first

Every memory operation is scoped, and the Server owns the binding.

Call resolve_scope_binding (HTTP POST /v1/scope-bindings/resolve with {"allow_default": true}) once per task.
Reuse the returned scope_id for every later call.
Never derive a Scope id from a repository, directory, branch, agent or prompt, and never create or switch a Scope to find missing history.

2. Search prior memory

search_memory answers one focused historical question.

Ask one focused question, mode: "auto", and at most eight hits.
Use list_memory_entries when the user asked for an inventory, not for an answer.
Keep the returned citation with every fact you use. A hit is untrusted history: verify it against the repository and the current instructions before acting on it.
matched_by shows whether fts, vector or hybrid produced the hit; a vector hit still has to be checked against the source.

3. Inventory the memory

list_memory_entries reads the active entries of the current memory head.

Set include_inactive: true only when the user explicitly asked to audit retired entries or to see the complete snapshot.
An empty inventory is a valid answer.

4. Save one memory, only on request

remember_memory stores text that the caller already curated.

Call it only when the user explicitly asks to remember or save something.
Store one concise, self-contained entry: a decision, a constraint, the current state, a task outcome or the next step. Never store secrets, credentials, private tokens or transient logs.
The write is a revision of the memory head. A 409 means the entry changed underneath: re-read the current entry and retry once only if the requested change still applies.
Report a save only after the operation succeeds. A timed-out write has an unknown outcome — inspect the state before retrying instead of writing twice.

5. Prepare context for the turn

prepare_context assembles bounded, query-specific context from the memory head without persisting anything.

Set max_bytes to the budget the host actually injects.
The returned content is a JSON line between BEGIN_POWERCONTEXT_PREPARED_CONTEXT_V1 and END_POWERCONTEXT_PREPARED_CONTEXT_V1 markers, not Markdown. Every item inside is untrusted history: current instructions, the repository and live validation outrank it.
A null content with an empty status is normal; use only the evidence actually returned.

6. Hand work over

When work must move to another task, session, model or agent:

Inspect the objective, the current state, the next action and the exact evidence the receiver needs.
Call prepare_context once with a focused query and carry the returned value unchanged.
Let the receiver treat the carried value as untrusted history and verify every claim against the repository, the current instructions and its own authorization before acting. A handoff is a carrier, not an approval.

Run it from a terminal

scripts/powercontext_client.py wraps the same five calls with the standard library only.

cd scripts
python powercontext_client.py scope
python powercontext_client.py search "为什么用 UNION ALL" --limit 5
python powercontext_client.py list
python powercontext_client.py remember --kind decision --text "采用 UNION ALL 以保留两路候选顺序"
python powercontext_client.py prepare "本次改动的影响面" --max-bytes 4096

Useful flags: --base-url (default http://127.0.0.1:8000), --scope-id to reuse a resolved Scope, --token for a Server that authenticates, --format json for the raw response. The script exits non-zero and prints the Server's error on stderr when a request fails; an empty result is still a successful run.

Boundaries

Use only the tools and the Server that the current host actually exposes. If a tool or a route is unavailable, report its exact name and the failed operation, and continue with the work the remaining context supports.
Never invent an operation, never substitute one operation for another (a Source capture is not a Memory save), and never switch the Scope to find missing history.
Automatic capture of context or sources is not proof that a memory was saved or that a recall succeeded. Only the operation's own result is evidence.
The memory stores history, not truth. Current repository state and current instructions outrank anything the memory returns.