Skip to main content

Memory

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:
HalfWhat it doesWhen it runs
GenerationWrites what the agent learned into memory filesAfter a turn completes, in a background memory agent
ConsumptionLoads memory files into the agent's contextAt session initialization, and on explicit refresh
Language availability: TypeScript, Python, Java. The capabilities on this page come from the TypeScript 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.
import { query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'Add a health check endpoint and run the tests',
  options: {
    memory: { mode: 'native' },
  },
})) {
  console.log(message);
}
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 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.
ScopeRoot idHolds
UseruserKnowledge that follows the operator across every project
ProjectprojectKnowledge specific to the current working directory
Disable either one per query:
// Project knowledge only — do not read or write user-level memory
options: {
  memory: { mode: 'native', userScope: false },
}
Native mode requires at least one enabled scope. Disabling both throws:
native mode requires at least one enabled scope; use memory: {} to disable SDK memory
Python rejects this with 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.
options: {
  memory: {},
}

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

options: {
  memory: {
    mode: 'custom',
    generation: {
      roots: [
        { id: 'team', path: '/srv/knowledge/team', access: 'read' },
        { id: 'service', path: '/srv/knowledge/checkout', indexFile: 'INDEX.md' },
      ],
      prompt: 'Record only deployment steps and failure signatures.',
    },
  },
}
Each root is a directory the memory agent may use:
FieldTypeDefaultDescription
idstring—Stable identifier used in prompts, initialization, and results
pathstring—Directory on the machine running Qoder CLI
access'read' | 'read-write''read-write'Whether the memory agent may write to this root
indexFilestring—Relative index path inside the root. Omit when every file is content
In Java, create a root with 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.
options: {
  memory: {
    mode: 'custom',
    generation: {
      turnComplete: {
        shouldGenerate: async (input, { signal }) => {
          if (input.prompt.length < 40) {
            return { run: false, reason: 'prompt too short to be worth remembering' };
          }
          return { run: true };
        },
        timeoutMs: 5_000,
        onGateError: 'skip',
      },
    },
  },
}
The callback receives the completed turn's 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.
FieldTypeDefaultDescription
enabledbooleantrueWhether turn-complete generation runs at all
shouldGeneratecallback—Product-side gate. Omit to use runtime guards only
timeoutMsnumber10000Maximum 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.
options: {
  memory: {
    mode: 'custom',
    consumption: {
      files: [
        { id: 'conventions', path: '/srv/knowledge/CONVENTIONS.md', required: true },
        { id: 'runbook', path: '/srv/knowledge/RUNBOOK.md' },
      ],
      maxTokens: 4_000,
      overflow: 'truncate',
      failureMode: 'fail_query',
    },
  },
}
Files are injected in array order, and id becomes the injected section name.
FieldTypeDefaultDescription
enabledbooleantrueWhether memory is loaded at all
filesMemoryConsumptionFile[]—Explicit files. Replaces native auto-memory
maxTokensnumber—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
In Python, the fields are 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:
options: {
  memory: {
    mode: 'native',
    generation: {
      onResult: (result) => {
        console.log(`[memory] ${result.status} in ${result.durationMs}ms`);
        for (const file of result.writtenFiles) {
          console.log(`  wrote ${file.rootId}:${file.path}`);
        }
      },
    },
    consumption: {
      onResult: (result) => {
        for (const file of result.files) {
          console.log(`  loaded ${file.id}: ${file.status}`);
        }
      },
    },
  },
}
Or read the same payloads off the message stream, as 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:
for await (const message of q) {
  if (message.type === 'system' && message.subtype === 'memory_generation') {
    console.log(message.result.status);
  }
}
In Java, result callbacks return 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:
StatusMeaning
savedEvery written file succeeded
partialAt least one file succeeded and one failed — inspect failedFiles
no_changeThe attempt ran and found nothing new to record
skippedThe attempt did not run, for example because a gate returned run: false
failedThe attempt ran and produced no successful write
Consumption reports 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.
const q = query({ prompt: userMessages(), options: { memory: { mode: 'native' } } });

// Wait for pending turn-complete generation before shutting down or asserting on files
await q.flushMemory();

// Reload configured memory files after an external process changed them
await q.refreshMemory();
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 to drainTimeoutMs. 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 is controlRequestTimeoutMs.
  • When the session has not enabled Memory, both methods fail with UnsupportedCliCapabilityException without 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 ResultMessage does not mean the stream has ended, so read it to the end.
In Python, QoderSDKClient provides flush_memory() and refresh_memory():
  • Concurrent flush_memory() calls share one request.
  • Without the daemon option, a one-shot query() flushes automatically before ending input, and the client flushes automatically on disconnect() or when leaving async with. An automatic flush failure is only logged and closing continues; call flush_memory() explicitly when you need to confirm success.
  • With the daemon option, if the CLI declares daemon_async_session_teardown_v1, neither a one-shot query() 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, use QoderSDKClient, call await client.flush_memory() before closing, and check the generation result.
  • When the CLI has not enabled memory for the SDK, both methods raise RuntimeError without 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:
const init = await q.initializationResult();
console.log(init.memory);
// {
//   enabled: true,
//   requester: 'sdk',
//   mode: 'native',
//   generationEnabled: true,
//   turnCompleteEnabled: true,
//   consumptionEnabled: true,
//   roots: [{ id: 'user', access: 'read-write' }, { id: 'project', access: 'read-write' }]
// }
When 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