hidb4ai · Oct 19, 2026 · Oct 17, 2026 · Oct 18, 2026
@@ -206,6 +206,12 @@ powercontext setup codex --ref powercontext-v1.3.0
 powercontext doctor codex
 ```
 
+Before sending the first message in a new Codex session, open `/hooks` and, when prompted, trust the PowerContext
+hooks. Without an enabled `UserPromptSubmit` hook, automatic prompt capture and recall do not run, even if MCP connects.
+See [first-session checks and recovery](docs/en/docs/integrations/codex.md#first-session-hook-trust).
+After the first check below, use the [capability and trigger guide](docs/en/docs/get-started/quickstart.md#5-choose-your-next-workflow)
+to try all seven Artifact families, Source, and Tag. Basic memory needs no separate Server model API; the Agent still uses its own model.
+
 ### 2. Verify the first end-to-end result
 
 This checks the path that makes PowerContext useful: Source capture → background processing → cross-session recall. In

@@ -170,6 +170,12 @@ powercontext setup codex --ref powercontext-v1.3.0
 powercontext doctor codex
 ```
 
+在新 Codex 会话发送第一条消息前，打开 `/hooks` 检查 PowerContext Hook，并在收到提示时授予信任。
+`UserPromptSubmit` Hook 未启用时，即使 MCP 连通，也不会自动采集输入或召回上下文。
+检查与恢复步骤见[首次会话 Hook 信任](docs/zh/docs/integrations/codex.md#首次会话-hook-信任)。
+完成下面的首次验收后，可按[能力与触发指南](docs/zh/docs/get-started/quickstart.md#5-选择下一项工作流)
+体验七类 Artifact、Source 和 Tag。基础记忆无需独立的 Server 模型 API；Agent 仍使用自己的模型。
+
 ### 2. 验收第一条端到端结果
 
 这一步检查 PowerContext 真正有用的链路：Source 采集 → 后台处理 → 跨会话召回。

@@ -161,6 +161,12 @@ powercontext setup codex --ref powercontext-v1.3.0
 powercontext doctor codex
 ```
 
+新しい Codex セッションで最初のメッセージを送る前に、`/hooks` で PowerContext Hook を確認し、求められたら信頼を許可してください。
+`UserPromptSubmit` Hook が無効な場合、MCP に接続できても入力の自動取得と想起は動作しません。
+[初回確認と復旧](docs/en/docs/integrations/codex.md#first-session-hook-trust)を参照してください。
+以下の確認後は、[機能と操作のガイド](docs/en/docs/get-started/quickstart.md#5-choose-your-next-workflow)から
+7 種類の Artifact、Source、Tag を試せます。Basic memory は Server 用の独立したモデル API が不要ですが、Agent 自身のモデルは使用します。
+
 ### 2. 最初のエンドツーエンド結果を確認する
 
 この確認では、PowerContext が役立つ流れを検証します：Source の取得 → バックグラウンド処理 → セッションをまたぐ想起。

@@ -133,7 +133,7 @@ immediately generate content. To test existing input immediately, see Profile fl
 
 ## Verify extraction and recall
 
-Follow the primary [Quick Start check](quickstart.md#4-verify-topic-memory-with-ordinary-conversation):
+Follow the primary [Quick Start check](quickstart.md#4-verify-memory-in-your-selected-mode):
 
 1. Agent input arrives as Source evidence in the bound Scope.
 2. Topic Memory contains a related topic and evidence.

@@ -41,20 +41,29 @@ even after the family head advances.
 
 ## Artifact families currently supported
 
-The code's write-capable families are `memory`, `experience`, `skill`, `handoff`, `profile`, and `prompt`. They share
-immutable Revisions and exact references, but expose different operations: Memory stores durable facts, Experience and
-Skill go through Candidate review, Handoff records work continuity, Profile stores Scope background, and Prompt stores
-Scope-level operational configuration.
+The current runtime supports seven families: `atomic-memory`, `experience`, `skill`, `handoff`, `profile`, `prompt`,
+and `topic-memory`. They share immutable Revisions and exact references, but expose different operations. Atomic Memory
+stores individual facts and decisions; Experience and Skill generation proposals go through Candidate review; Handoff
+records work continuity; Profile stores Scope background; Prompt configures operations; Topic Memory organizes topics.
+Direct Artifact writes follow each family's validation and permissions rather than automatically creating Candidates.
 
-Read APIs also expose the specialized `topic-memory` family. Topic Memory is produced by background Source processing and
-is used through `flush`, `search`, and `get`; it currently has no generic create, update, delete, or retire operation. A
-Source is evidence rather than an Artifact. A Tag is metadata for Memory, Experience, Skill, and Handoff rather than an
-Artifact family.
+[Topic Memory](../workflows/topic-memory.md#write-through-the-generic-artifact-interfaces) supports generic creation and
+replacement as well as background Source processing and its dedicated `flush`, `search`, and `get` operations.
+A Source is evidence rather than an Artifact. [Tags](../workflows/manage-artifact-tags.md) organize saved Artifacts in all
+seven current families without changing content Revisions; Tag is not a separate Artifact family.
+
+Some API schemas retain the legacy `memory` identifier for compatibility; it is not a current writable family.
+Do not infer general legacy collection-read support from that identifier. For old data and reference handling, follow
+[Atomic Memory migration](../operate/atomic-memory-migration.md).
 
 ## Memory stores durable project knowledge
 
-Memory is a revisioned Artifact family for reusable decisions, constraints, facts, state, and next steps. Entries can
-be active or inactive; retiring an entry removes it from active recall without deleting its history.
+Each Atomic Memory is an independent revisioned Artifact for a reusable decision, constraint, fact, status, or next
+step. Its current state is `active`, `forgotten`, `merged`, or `retired`; ordinary recall selects active records only.
+The public lifecycle operation accepts `forgotten` with the exact Artifact reference and current `state_version`,
+removing the record from active recall without deleting history. Merge and restoration have separate operations;
+the four readable states are not four freely assignable lifecycle values. See [Atomic Memory](../workflows/atomic-memory.md)
+for content revisions, state changes, and exact historical reads.
 
 Explicit Memory writes do not require a model. Source-based extraction does require a configured generation pipeline.
 Memory is durable and searchable, unlike the temporary context prepared for one Agent turn. See
@@ -111,7 +120,7 @@ HTTP is the complete remote application contract. The Python Client provides typ
 curated Agent-facing projection, while the CLI covers setup, diagnostics, Server operation, and human review tasks.
 Core protocols support applications that assemble their own Source, Artifact, and Trigger implementations.
 
-Model generation, human Review, and execution authority remain separate. A model can propose content, Review can
+Model generation, Review, and execution authority remain separate. A model can propose content, Review can
 approve an Artifact Revision, and export can create a host-local copy. None of those steps grants an Agent permission
 to execute instructions.
 

@@ -69,9 +69,11 @@ configuration.
 Approval, installation, and execution are three separate steps:
 
 1. **Approval** creates an immutable Skill Revision in PowerContext.
-2. **Export / install** copies an exact Revision to the Agent host (for example via Remote Skill distribution or
-   manual `download_skill_package`).
-3. **Execution** happens when the Agent's host discovers and loads the installed `SKILL.md`.
+2. **Export / install** places the exact Revision in a directory the Agent host discovers. For Codex, follow
+   [Create and export a Skill](../workflows/create-and-export-skill.md) with `powercontext skill export --target codex`.
+   Downloading a package through `download_skill_package` alone does not establish host installation or discovery.
+3. **Discovery and use** happen on the Agent host. Verify that it discovers the exported `SKILL.md`; loading it does
+   not itself authorize execution of its instructions.
 
 Approving a Skill does not install it; installing it does not execute it. Each step is explicit so that you keep
 control over what runs where.

@@ -101,9 +101,18 @@ powercontext doctor codex
 codex
 ```
 
-Confirm that the PowerContext Hook and MCP have both loaded in Codex. For a non-default address, follow the Codex
-connection instructions in `.env.next-steps.md`: the installed plugin's `.mcp.json` must use the same Server as the Hook,
-with credentials configured when authentication is enabled. Installing the plugin does not start the Server.
+Before sending the first message in the new session:
+
+1. Open `/hooks`, inspect the PowerContext hooks, and grant trust when prompted. `SessionStart` resolves the Session Scope;
+   `UserPromptSubmit` automatically prepares relevant context and captures your input as a Source.
+2. Confirm that PowerContext MCP tools are available. Tool discovery and Hook execution are separate checks.
+3. If you skipped or denied trust, use the [Hook recovery steps](../integrations/codex.md#first-session-hook-trust)
+   before testing capture. Without an enabled `UserPromptSubmit` hook, automatic capture and recall do not run.
+
+For a non-default address, follow the Codex connection instructions in `.env.next-steps.md`: the installed plugin's
+`.mcp.json` must use the same Server as the Hook, with credentials configured when authentication is enabled.
+Installing the plugin does not start the Server. `doctor codex` checks installation, connection, and tool coverage;
+it does not establish Hook trust, execution, or successful memory processing.
 
 These commands use Codex CLI. A desktop app may not inherit terminal environment variables. Before testing in the
 desktop app, verify that both its Hook and MCP receive the same URL and Scope, and credentials when authentication
@@ -113,7 +122,30 @@ Full memory also needs a generation policy for this real Scope to use Profile. F
 [Profile policy steps](configure-models.md#enable-a-profile-policy-for-the-scope) to read its current version and update it;
 saving the configuration does not perform this operation.
 
-## 4. Verify Topic Memory with ordinary conversation
+## 4. Verify memory in your selected mode
+
+Both modes can capture Source evidence when the Hook is enabled. Basic memory needs no separate Server model API;
+the Agent still uses its own model. Choose the check matching your configuration.
+
+### Basic memory: explicitly save and retrieve
+
+Ask in the bound Codex session:
+
+```text
+Save this decision to PowerContext: the Aurora acceptance project uses uv for Python dependencies.
+Return the saved record reference.
+```
+
+Check the actual write result, then open a new session with the same Scope and ask:
+
+```text
+Search PowerContext for Aurora's Python dependency-management decision, with its citation.
+```
+
+Verify the saved content and citation. A conversational acknowledgement is not proof of a write; this check verifies
+explicit save and retrieval, not automatic extraction or Topic Memory generation.
+
+### Full memory: Source processing and Topic Memory
 
 Send a concrete project decision in the new Codex session:
 
@@ -135,9 +167,48 @@ Correct content and its citation complete the capture → evolution → cross-se
 `doctor codex` only checks installation and connectivity; it does not prove this workflow. The model may merge evidence
 or decide that no update is needed, so not every message creates a new memory.
 
-In basic-memory mode, explicitly ask the Agent to save Aurora's uv decision in PowerContext, then search for it in a
-new session and verify its citation. That test does not cover automatic extraction. Profile, Experience, and Skill have
-additional triggers or review requirements; see [Capability behavior](configure-models.md#full-capabilities-do-not-generate-every-artifact-from-every-message).
+Full memory does not generate every Artifact from every message. Profile, Experience, and Skill have additional
+triggers or review requirements; see [Capability behavior](configure-models.md#full-capabilities-do-not-generate-every-artifact-from-every-message).
+
+| Check | Evidence of success |
+| --- | --- |
+| Installation and MCP discovery | `doctor codex` reports connection and tool coverage; it does not verify Hook execution |
+| Prompt capture | The actual input appears as a Source in the bound Scope |
+| Explicit Memory save | A real saved record reference, with matching content found in a new session |
+| Automatic processing | A related Topic Memory and its Source evidence; check updates without assuming a fixed completion time |
+| Cross-session retrieval | Correct content with a citation, using the same Server and Scope |
+
+## 5. Choose your next workflow
+
+The seven Artifact families have different inputs and consumption paths. Source is evidence and Tag is metadata;
+neither is an Artifact family. The examples below are requests, not guaranteed keyword triggers. Use the actual tools
+available in your connection; follow the linked HTTP/CLI workflow for operations without a dedicated MCP tool.
+Read the [Artifact overview](faq.md#artifact-families-at-a-glance) for conceptual differences.
+
+| Capability and purpose | Request or starting point | Requirements and result |
+| --- | --- | --- |
+| [Atomic Memory](../workflows/atomic-memory.md): individual decisions and constraints | “Remember in PowerContext that Aurora uses uv.” | `remember_memory` saves explicitly without Server generation; search with `search_memory` and verify the record citation. Automatic extraction needs Generation and scheduling. |
+| [Topic Memory](../workflows/topic-memory.md): evolving topic summaries | “Search Aurora's deployment topics, then read the relevant revision.” | `search_topic_memory` / `get_topic_memory` read existing topics. Automatic generation needs configured Generation and scheduling; inspect the topic's Source references. |
+| [Profile](../workflows/use-profiles.md): Scope background | Follow the Profile workflow to generate and inspect the Scope's profile. | Automatic generation needs Generation, a Scope policy, and scheduling; policy selects review or automatic commit. Recall requires explicit assembly selection. |
+| [Handoff](../workflows/handoff-with-codex.md): continue unfinished work | “Hand off this work” for temporary transfer; “Commit a durable handoff” for a milestone; “Preview the handoff; do not commit” for a read-only preview. | The shipped Skill routes a transfer request to the Handoff workflow. Distinguish temporary prepared content from an exact committed Revision; no background extraction is required. |
+| [Experience](../workflows/create-and-review-experience.md): reusable lessons | “Generate an Experience candidate from these exact Source references.” | `generate_experience` needs Generation; `propose_experience` accepts caller-authored content without generation. Inspect the pending Candidate or `no_op`; generated proposals need review before reuse. |
+| [Skill](../workflows/create-and-export-skill.md): reusable procedures | “Generate a Skill candidate from these exact Source references.” | `generate_skill` needs Generation; `propose_skill` accepts complete content without generation. Review the candidate, then explicitly export the exact approved Revision to the Agent host. |
+| [Prompt](../workflows/manage-prompts.md): operational generation instructions | Read and configure an operation's Prompt through the HTTP workflow. | This is not a captured user message. Check customization support and `scope.admin` when access is enforced; saving a Revision does not enable an operation or reprocess history. |
+| [Source](../workflows/sources.md): original evidence | Send a distinctive ordinary message; for explicit material use `capture_content_source`. | Hook capture needs no generation model. Verify the Source; capture alone does not establish Memory generation. Do not infer capture of all Agent replies. |
+| [Tag](../workflows/manage-artifact-tags.md): organize saved Artifacts | Use the Python Client or HTTP workflow to label an exact Artifact and query the label. | No model is required. Use the existing Artifact ID, permissions, and tag ETag; verify the saved label and query result. There is no dedicated MCP tag-management tool. |
+
+### Plugin guidance and managed Skills
+
+The installed plugin includes `powercontext-project-context`, which routes requests to the relevant workflow. It is
+separate from a managed Skill stored in PowerContext. If the routing Skill is absent from the host catalog, check plugin
+installation; a natural-language example does not add missing tools or grant permission.
+
+For a generated managed Skill, inspect the Candidate and obtain an authorized review decision. Approval creates an
+immutable Revision; it does not install or execute it. Follow [Create and export a Skill](../workflows/create-and-export-skill.md)
+to export the exact approved Revision with `powercontext skill export --target codex` to the intended host-local
+`.agents/skills/<skill-name>` directory. Confirm that Codex discovers the exported Skill; restart if it does not appear.
+Direct Artifact writes have their own contract; the Candidate sequence here describes generation and proposal workflows.
+Review authority depends on permissions, not on whether the reviewer is human. Discovery does not grant execution authority.
 
 ## Continue