Use Topic Memory

Topic Memory is an Artifact family for long-running topics. It turns accumulated Sources in one Scope into a title, summary, and progressively disclosed detail, so an Agent can locate a topic first and read the full detail only when needed; callers can also submit complete topic content directly through the generic interfaces in Manage Artifacts. It does not replace Memory, Experience, Skill, or Handoff.

Topic Memory is Scope-local. Capturing a Source does not synchronously create a topic; configured background processing must advance it.

It is useful for questions such as “what have we decided about Aurora's deployment?” when the answer has changed across several conversations. Topic Memory is historical evidence. It does not override the current prompt, live project state, authorization, or the Agent's other instructions.

How it differs from other context

Topic Memory is not created by an explicit Memory write. A meaningful Source window, supported Generation settings, and enabled Topic processing are required. The model can revise an existing topic, merge evidence, or decide that no new topic revision is warranted.

Registered remote Source observations can share a processing window with built-in Sources. Topic processing uses the stored standard text-evidence projection when available, or the captured payload otherwise; it does not require a local adapter for the remote Source. Published revisions retain the original Source references for provenance.

Lifecycle

Source → background cursor → flush request → new or updated immutable Topic Memory Revision
      → search current heads → get an exact Revision

flush persists a processing request without waiting for background work. accepted means the request was accepted and idle means the Source cursor is already current; neither means that a particular topic has been generated.

Enable automatic Topic Memory

Use the configuration wizard to select full memory, or configure the deployment directly. Topic Memory needs:

• a supported Generation model and valid provider credentials;
• a positive POWERCONTEXT_SERVER_RUNTIME_TOPIC_MEMORY_SCHEDULE_SECONDS value to admit new automatic work;
• meaningful Source evidence in the Scope.

Embedding is optional for Topic Memory itself. Configure a compatible Embedding model and dimension when the deployment should offer vector or hybrid retrieval. The Server exposes the selected retrieval mode in each search response; callers do not choose arbitrary retrieval controls.

The schedule is an admission interval, not a completion deadline. Topic generation also has provider and Worker timeouts. An unset schedule disables new automatic admission but does not discard already accepted work. For SQLite deployments, Topic Workers with a Generation model require a persistent, file-backed database rather than an in-memory database. See Configure models and full memory and Configuration options for the complete settings and deployment constraints.

Verify a real topic

Use the Quick Start Topic Memory check for a full Agent and Dashboard acceptance flow:

1. Send a concrete project decision in a new session.
2. Confirm that the input appears as a Source in the same Scope.
3. Wait for the configured inspection interval and model processing, then confirm a related Topic Memory exists.
4. Send a related update and check the topic content or revision history.
5. Start a new session with the same Scope and retrieve the topic with citations.

Do not treat doctor codex, a readiness response, or the passage of one minute as proof that the business flow works. Those checks cover installation or service state, not Source capture, generation, publication, and new-session retrieval.

Request processing

The caller needs scope.contribute access to the target Scope. For the HTTP examples below, use the Server URL and credentials from your trusted environment and include an Authorization: Bearer <token> header when Access is enabled. Replace project-a with the same real Scope ID for every request.

Send a flush request:

POST /v1/topic-memory/flush
Content-Type: application/json

{"scope_id":"project-a"}

The response contains only status. Source capture, topic generation, and index updates run asynchronously through the configured worker. Without a generation model or background processing capability, flush cannot create topics by itself. Whether vector or hybrid retrieval is available is a deployment choice; the caller does not select it in this request.

Search current topics

Search requires scope.read access. Send a non-empty scope_id and query, with an optional limit from 1 to 20 (default 10):

POST /v1/topic-memory/search
Content-Type: application/json

{"scope_id":"project-a","query":"release process","limit":5}

The response reports the deployment's actual mode (fts or hybrid) and hits. Each hit contains an exact artifact reference, title, summary, an optional snippet, score, and matched_by. Search sees only current Topic Memory heads in the current Scope; it does not search across Scopes or accept a caller-selected retrieval mode.

Read exact detail

Do not reconstruct the latest version from a title. Pass the artifact from a search hit (family, artifact_id, and revision) unchanged to get to read an immutable snapshot and its direct Source evidence:

POST /v1/topic-memory/get
Content-Type: application/json

{
  "scope_id":"project-a",
  "artifact":{
    "family":"topic-memory",
    "artifact_id":"topic-release",
    "revision":3
  }
}

The response contains title, summary, full detail, and source_refs. Even after the current topic head advances, the exact reference resolves to the same historical Revision for audit, citation, and progressive disclosure.

Write through the generic Artifact interfaces

Besides Source processing, Topic Memory also uses the generic interfaces in Manage Artifacts:

Creation requires scope.contribute on the target Scope, and the request body carries the complete title, summary, and detail. The content skips semantic generation: topic content, the current head, chunks, and the retrieval indexes enabled by the deployment are committed in one operation, so generic reads and the dedicated search see the same topic version. A replace requires current scope.admin access, creates the next immutable Revision, and must carry the current head's If-Match.

Manage tags as described in Organize with tags; whole-Artifact Topic Memory tags are read with scope.read and modified with scope.admin.

Publish one exact Revision into another Scope with POST /v1/artifact-publications, which requires scope.admin in both the source and target Scopes. Publication creates an independent identity in the target Scope and carries its retrieval indexes; tags and direct Sources are not copied.

Assemble into PreparedContext

To inject topic summaries into one Agent turn, add topic-memory explicitly to assembly in POST /v1/context/prepare, for example:

{
  "scope_id": "project-a",
  "query": "release process",
  "assembly": {
    "sections": [
      {"family": "topic-memory", "limit": 2}
    ]
  }
}

When assembly is omitted, the Runtime may retain the default Topic Memory recall when the deployment and data support it. An empty sections array disables candidate artifact recall. PreparedContext is still temporary and does not create a new Topic Memory Revision. An explicit assembly: {} uses the Memory and Experience defaults and excludes Topic Memory. The prepared result includes bounded title, summary, optional matching snippet, Scope, and exact revision citations; read the exact revision to retrieve full Topic detail. See Prepare context text for grouped Markdown rules.

Search and read through MCP

MCP exposes the read-only search_topic_memory and get_topic_memory tools. The Agent should search with a focused query and pass the complete returned Artifact reference unchanged to the exact-read operation. The flush operation is HTTP-only and is not exposed as an MCP tool.

Current boundaries

• The generic interfaces do not accept Topic Memory delete or retire operations; topics are stored as immutable Revisions, and background processing or an explicit write advances the current head.
• Source capture does not synchronously generate a topic; background processing and the required generation capability are needed.
• Backups, recovery, worker availability, and retrieval failures belong to deployment and operations, not this lifecycle.

Diagnose missing or stale topics

For service and model failures, see Troubleshoot. For the processing cursor, retries, budgets, and deployment roles, see Configuration options and the Topic Memory RFC.