Let agents carry knowledge across turns and sessions with native memory, or take over generation and consumption yourself.
Memory lets an agent keep the knowledge it gains in one session and reuse it later. A project's build command, test layout, and code conventions no longer have to be rediscovered on every run.
Qoder Agent SDK memory has two halves — generation and consumption — which can be configured independently:
Language availability: TypeScript, Python, Java.
The capabilities on this page come from the TypeScript
In native mode the only configurable parts are the two scope switches and the result callbacks. Everything else — the storage location, the generation prompt, the loading budget — stays owned by the runtime and improves with each release. Java's
Native memory has two scopes. Both are enabled by default.
Disable either one per query:
Native mode requires at least one enabled scope. Disabling both throws:
Python rejects this with
An empty object is the explicit "off" switch, equivalent to omitting
Each root is a directory the memory agent may use:
In Java, create a root with
Generation normally starts on every completed turn.
The callback receives the completed turn's
Passing explicit
Files are injected in array order, and
In Python, the fields are
Memory runs in the background, so surface its outcome rather than assuming success. Two paths are available.
Register callbacks, which work in both
Or read the same payloads off the message stream, as
In Java, result callbacks return
Consumption reports
Two methods on the query handle the timing problems that background generation creates.
Memory options are negotiated with the runtime, so read back what actually took effect instead of trusting the request:
When
| Half | What it does | When it runs |
|---|---|---|
| Generation | Writes what the agent learned into memory files | After a turn completes, in a background memory agent |
| Consumption | Loads memory files into the agent's context | At session initialization, and on explicit refresh |
memory option, Python's QoderAgentOptions.memory, and Java's SessionOptions.Builder.memory(MemoryOptions), plus each SDK's runtime methods: flushMemory() / refreshMemory() in TypeScript and Java, and flush_memory() / refresh_memory() in Python. Python configuration fields use snake_case (such as user_scope and on_result); fields in callback inputs, results, and initialization info keep camelCase (such as turnIndex and writtenFiles).
Memory is supported only by the local CLI runtime, not by the experimental Cloud Agent runtime: in TypeScript and Python, passing memory while Cloud Agent is enabled throws before connecting, and calling flushMemory() / refreshMemory() (flush_memory() / refresh_memory() in Python) while Cloud Agent is enabled also fails.
Enable native memory
mode: 'native' (TypeScript) / {"mode": "native"} (Python) / MemoryOptions.nativeBuilder() (Java) delegates all behavior to Qoder CLI defaults. This is the recommended starting point: the runtime decides what is worth remembering, where to store it, and when to load it.
MemoryOptions builder also has drainTimeoutMs(long), which bounds how long an explicit flush or a normal close waits for memory processing. The default is 60000 ms.
Choose memory scopes
Native memory has two scopes. Both are enabled by default.
| Scope | Root id | Holds |
|---|---|---|
| User | user | Knowledge that follows the operator across every project |
| Project | project | Knowledge specific to the current working directory |
TypeError before connecting to the CLI; the message is native memory requires at least one enabled scope; use memory={} to disable. In Java, build() on MemoryOptions throws IllegalArgumentException, and the CLI is not started.
Disable memory
An empty object is the explicit "off" switch, equivalent to omitting memory entirely. No memory configuration is sent to the runtime. In Python, pass memory={} or omit memory. In Java, use MemoryOptions.disabled(), which is also the default; memory(null) throws NullPointerException.
Override generation and consumption
mode: 'custom' (TypeScript) / {"mode": "custom"} (Python) / MemoryOptions.customBuilder() (Java) applies your overrides and inherits everything you omit from the runtime defaults. Use it when the application owns where memory lives or what counts as worth remembering.
Control what gets written
| Field | Type | Default | Description |
|---|---|---|---|
id | string | — | Stable identifier used in prompts, initialization, and results |
path | string | — | Directory on the machine running Qoder CLI |
access | 'read' | 'read-write' | 'read-write' | Whether the memory agent may write to this root |
indexFile | string | — | Relative index path inside the root. Omit when every file is content |
MemoryRoot.builder(id, path). access is MemoryRoot.Access.READ or READ_WRITE (the default). indexFile must be a relative path inside the root; an absolute path or a path containing .. throws IllegalArgumentException. roots must not be empty, and id values must be unique.
In Python, root fields are id, path, access, and index_file. index_file must stay inside the root, roots must not be empty, and id values must be unique; otherwise the options are rejected with TypeError.
Decide per turn whether to write
Generation normally starts on every completed turn. shouldGenerate lets the application veto an attempt — useful to skip trivial turns, respect a per-tenant budget, or avoid writing during a read-only review.
prompt and response, plus sessionId, cwd, and a one-based turnIndex. Returning run: false (MemoryGenerationGateResult.skip(reason) in Java) emits a skipped result instead of starting the background agent.
In Java, the callback returns CompletionStage<MemoryGenerationGateResult> and runs on the client's callbackExecutor. The second argument is a cancellation token that fires when the CLI cancels or the callback times out; the callback should check it and stop work that is no longer needed. onGateError maps to OnGateError.SKIP / REPORT_FAILED.
In Python, the gate should_generate(turn, context) can be a regular or an async function. turn is the turn input and keeps camelCase fields (such as turnIndex); when the CLI cancels the request, context["signal"] (an asyncio.Event) is set. The return value must be a dict with a boolean run; anything else is reported to the CLI as an error. The configuration fields are should_generate, timeout_ms, and on_gate_error.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whether turn-complete generation runs at all |
shouldGenerate | callback | — | Product-side gate. Omit to use runtime guards only |
timeoutMs | number | 10000 | Maximum time allowed for the gate |
onGateError | 'skip' | 'report_failed' | 'skip' | How a callback error or timeout is reported |
Control what gets loaded
Passing explicit files replaces native auto-memory for this query. Static instructions still load.
id becomes the injected section name.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Whether memory is loaded at all |
files | MemoryConsumptionFile[] | — | Explicit files. Replaces native auto-memory |
maxTokens | number | — | Shared budget across all explicit files |
overflow | 'truncate' | 'fail_query' | 'truncate' | Behavior when content exceeds maxTokens |
failureMode | 'best_effort' | 'fail_query' | 'best_effort' | Read-failure behavior. Only required files can fail the query |
files, max_tokens, overflow, and failure_mode, with the same values as the table above.
In Java, overflow and failureMode take values of the MemoryConsumptionOptions.Overflow and MemoryConsumptionOptions.FailureMode enums. files must not be empty, and id values must be unique.
Observe what memory did
Memory runs in the background, so surface its outcome rather than assuming success. Two paths are available.
Register callbacks, which work in both native and custom mode:
system messages with subtype memory_generation and memory_consumption. In Python these are MemoryGenerationMessage and MemoryConsumptionMessage (subclasses of SystemMessage), with the result in .result. In Java these are MemoryGenerationMessage and MemoryConsumptionMessage; call result() for the typed result:
CompletionStage<Void> and run on the callbackExecutor. An exception thrown by a callback does not affect the result messages in the stream and does not end the session.
In Python, result callbacks can be regular or async functions; an exception raised by a callback is only logged and does not affect the message stream.
Generation reports one of five outcomes:
| Status | Meaning |
|---|---|
saved | Every written file succeeded |
partial | At least one file succeeded and one failed — inspect failedFiles |
no_change | The attempt ran and found nothing new to record |
skipped | The attempt did not run, for example because a gate returned run: false |
failed | The attempt ran and produced no successful write |
success, partial, or failed, with a per-file status of loaded, missing, failed, or truncated. A missing file is not an error on its own — memory files may legitimately not exist yet on a first run.
Java represents these statuses as enums: MemoryGenerationResult.Status, MemoryConsumptionResult.Status, and MemoryConsumptionResult.FileStatus, with the uppercase form of the values above (for example SAVED, NO_CHANGE). A status the SDK does not recognize becomes UNKNOWN, and the raw value is available from wireStatus().
Control memory at runtime
Two methods on the query handle the timing problems that background generation creates.
flushMemory() matters most in CI and in tests: without it, a process that exits right after the final result message can terminate a generation attempt mid-write.
In Java, both QoderQuery and QoderSession provide these two methods, and they wait for initialization on their own:
flushMemory()waits for memory processing the CLI has already started, up todrainTimeoutMs. Completion does not mean every file was written; still check the generation results.refreshMemory()rereads the memory files with the current loading configuration without changing it. Its timeout iscontrolRequestTimeoutMs.- When the session has not enabled Memory, both methods fail with
UnsupportedCliCapabilityExceptionwithout sending a request. - After the final answer, a one-shot query waits for memory processing that has already started and keeps delivering Memory messages. The stream ends only after processing completes or times out. Receiving the
ResultMessagedoes not mean the stream has ended, so read it to the end.
QoderSDKClient provides flush_memory() and refresh_memory():
- Concurrent
flush_memory()calls share one request. - Without the
daemonoption, a one-shotquery()flushes automatically before ending input, and the client flushes automatically ondisconnect()or when leavingasync with. An automatic flush failure is only logged and closing continues; callflush_memory()explicitly when you need to confirm success. - With the
daemonoption, if the CLI declaresdaemon_async_session_teardown_v1, neither a one-shotquery()nor closing the client flushes automatically, so a completed close does not mean memory has been written. If you check memory files or start the next session right after closing, useQoderSDKClient, callawait client.flush_memory()before closing, and check the generation result. - When the CLI has not enabled memory for the SDK, both methods raise
RuntimeErrorwithout sending a request.
Verify the effective configuration
Memory options are negotiated with the runtime, so read back what actually took effect instead of trusting the request:
memory is omitted or set to {}, init.memory is undefined. In Python, read memory from the value returned by get_server_info(); its fields keep camelCase. In Java, when Memory is not enabled, memory() returns Optional.empty().
When Java explicitly enables Memory, the CLI must confirm during initialization that memory is enabled for the SDK before the SDK sends the first input. If the CLI does not confirm, initialization fails with UnsupportedCliCapabilityException.
Next steps
- Session Control — resume and fork sessions that carry memory
- External Session Storage — persist transcripts so another host can resume
- Track cost and usage — generation attempts report their own
usageandcredits