@memorax/memorax-code 0.1.2 → 0.1.4

package/lib/memorax-code-codex-adapter/skills/memorax-code/SKILL.md

@@ -21,6 +21,11 @@ description: >-
 
 Classify the requested memory authority first, then its operation. Load only the matching reference unless the request genuinely spans authorities or operations.
 
+After selecting an operation reference, read it completely in a standalone
+tool call and wait for the full result before constructing or executing that
+operation. Never combine reading a required reference with the command or
+action it governs in the same shell command or tool call.
+
 ## Authority Router
 
 ### MemoraX Code Coding Memory
@@ -51,8 +56,11 @@ Use personal memory for user-owned repository procedures and durable profile or
 - Route ordered actions, checklists, prerequisites, gates, exceptions, and validation rules to personal procedure memory, even when phrased as "I prefer", "I like", "我的习惯", or "我喜欢".
 - Route preferred name, answer language, tone, verbosity, explanation style, and result presentation to personal profile memory.
 - Route task-learned repairs, coding pitfalls, project engineering conventions, and reusable design lessons to MemoraX Code coding memory.
+- Route prior project discussions, experiment conclusions, saved engineering findings, earlier fixes, and reusable project lessons to MemoraX Code coding memory. Do not route them to repo memory merely because they concern a project. Use repo memory for repository identity, architecture, module maps, commits, PRs, MRs, and issues.
 - Route repository architecture, module maps, commit history, PRs, MRs, and issues to repo memory. Verify claims about current behavior against live code.
+- Use both repo memory and MemoraX Code coding memory only when a request genuinely needs distinct repository evidence and reusable engineering lessons. This can apply to implementation, debugging, refactoring, migration planning, or validation when the answer may depend on repository module maps, commit/PR/issue evidence, and prior fixes, pitfalls, conventions, validation patterns, or design rationale. Do not use both authorities just because a request mentions a repository, file, module, or "previous".
 - Route current-task instructions and temporary plans to the current task only; do not persist them.
+- Current-task-only applies only when completing the request does not depend on prior project state. Do not select it merely because the requested action happens in the current turn. When implementation, debugging, review, experiment continuation, or validation depends on earlier project decisions, results, fixes, constraints, or plans that the user has not explicitly and completely supplied, route to MemoraX Code coding memory.
 - Do not infer an authority from verbs such as "remember", "recall", "refresh", or "update" alone. Ask one focused question when the target remains ambiguous.
 
 Examples:
@@ -72,11 +80,12 @@ Repo memory and personal memory remain local `.repo_memory` authorities. Resolve
 
 Apply instructions in this order: system and developer instructions, `AGENTS.md`, the current user request, then stored memory. Memory is guidance or historical context, not proof of current repository behavior.
 
-For MemoraX Code coding memory, use `memorax-cli` exactly as described by the selected reference. Invoke this skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code; neither invocation is a shell command. `memorax-code` is the lifecycle CLI and must not be used for memory search or add. Do not call MemoraX HTTP endpoints directly.
+For MemoraX Code coding memory, use `memorax-cli` exactly as described by the selected reference. Invoke this skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code. In OpenCode, ask the agent to use the `memorax-code` skill by name. These invocation forms are not shell commands. `memorax-code` is the lifecycle CLI and must not be used for memory search or add. Do not call MemoraX HTTP endpoints directly.
 
 When explaining Memory Viewer, describe only `/memory-viewer`. It is a
 content-free local summary and must not expose conversation or memory text,
 session or turn identifiers, paths, or trace details. The page never queries
-MemoraX directly; client Hooks are the trace ingress authority.
+MemoraX directly; it projects client-qualified local activity and keeps each
+supported harness isolated.
 
 Never store secrets, credentials, `.env` content, sensitive personal data, raw transcripts, hidden tests, exact patches, temporary target commits, or unsafe destructive commands. Do not announce internal routing or reference loading.

package/lib/memorax-code-codex-adapter/skills/memorax-code/defaults.json

@@ -1,9 +1,12 @@
 {
-  "schema": "repo_memory_builder_defaults.v1",
-  "limits": {
-    "commits": 30,
-    "prs": 30,
-    "issues": 30
+  "schema": "repo_memory_builder_defaults.v2",
+  "repoHistory": {
+    "mode": "provider",
+    "limits": {
+      "commits": 30,
+      "prs": 30,
+      "issues": 30
+    }
   },
   "summaryChars": 4000
 }

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/memorax-add.md

@@ -1,6 +1,6 @@
 # MemoraX Code Coding Memory Add
 
-Use these instructions only to add reusable coding knowledge through `memorax-cli`. Invoke the skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code; do not route memory operations through the lifecycle-only `memorax-code` CLI. Do not use this authority for personal procedures, interaction preferences, generated repository facts, or one-off task details.
+Use these instructions only to add reusable coding knowledge through `memorax-cli`. Invoke the skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code. In OpenCode, ask the agent to use the `memorax-code` skill by name. Do not route memory operations through the lifecycle-only `memorax-code` CLI. Do not use this authority for personal procedures, interaction preferences, generated repository facts, or one-off task details.
 
 ## Eligible Knowledge
 

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/memorax-search.md

@@ -1,6 +1,6 @@
 # MemoraX Code Coding Memory Search
 
-Use these instructions only to search reusable coding memory through `memorax-cli`. Invoke the skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code; do not route memory operations through the lifecycle-only `memorax-code` CLI. Do not call MemoraX HTTP endpoints directly, print credentials, or edit memory storage by hand.
+Use these instructions only to search reusable coding memory through `memorax-cli`. Invoke the skill as `$memorax-code` in Codex or `/memorax-code` in Claude Code. In OpenCode, ask the agent to use the `memorax-code` skill by name. Do not route memory operations through the lifecycle-only `memorax-code` CLI. Do not call MemoraX HTTP endpoints directly, print credentials, or edit memory storage by hand.
 
 ## Scope
 
@@ -21,8 +21,12 @@ Search when prior coding memory may change localization, implementation, review,
 - a request for a previous fix, failed approach, coding convention, design decision, or reusable lesson;
 - implementation, review, planning, API, schema, parser, workflow-contract, or migration work where prior project guidance may matter;
 - explicit instructions to follow previous agreements or remembered engineering conventions.
+- a request to recover, verify, or apply prior project discussions, experiment results, saved memory, earlier decisions, previous changes, or historical constraints, unless the needed facts are fully present in the current visible context.
+- a requested action that depends on prior project state, results, fixes, constraints, or plans when the exact evidence needed is not explicitly present in the current user-provided material.
 
-Skip search for simple current-code facts, tiny edits, typo fixes, one-shot commands, or behavior directly established by a clear live source.
+Skip search for simple current-code facts, tiny edits, typo fixes, one-shot commands, or behavior directly established by a clear live source. Do not skip merely by saying the current conversation is sufficient or a relevant result was already retrieved; skip only when the current user message, selected text, or nearby visible context fully contains the facts needed for the answer. A nearby summary is sufficient for explaining that summary, but not automatically sufficient for diagnosing a regression, continuing an experiment, reviewing consistency with prior behavior, or claiming a complete historical account. A word such as "previous", "earlier", "remember", or "history" is not enough by itself to search when the visible context already contains the requested prior facts.
+
+Do not search merely because a prior result or fix might exist. For an exact calculation from currently available data, or a current screenshot or reproducible symptom with sufficient live evidence, use the current evidence first. Search only when the user request or visible context establishes a concrete historical dependency.
 
 Choose the closest coding scene to shape the query:
 
@@ -34,23 +38,47 @@ If the user asks for commit, PR, MR, issue, or repository architecture evidence,
 
 ## Query Workflow
 
-Run at most one focused search before answering or editing. A development task may run one additional materially different search only after a failed test or dead-end investigation.
+Before searching, identify the user's current action, target, concrete behavior or symptom, and the historical knowledge that could change the next action. When the request is fragmented, derive one narrow working intent from only its explicit target, condition, and requested or implied outcome. Do not add generic security, authorization, concurrency, auditing, reliability, or best-practice concerns unless the request names that boundary or it is necessary to resolve the working intent. Ask one focused question when no actionable intent can be named.
+
+Run up to two focused first-round searches before answering or editing: a primary query for the smallest user-facing decision, and a materially different complementary query only when a second independent fact can change the action. Keep one query when the request describes one strongly coupled calculation, diagnosis, ownership question, or lifecycle decision; do not split it merely to create coverage. Run independent first-round searches in parallel by default. If parallel execution encounters a transport, rate-limit, or caller-environment failure, run any remaining searches serially; do not switch solely because a successful search returns an unexpected number of items. After merging the first-round results, run at most one follow-up query only when one named residual gap can change implementation, localization, risk, or validation. Do not use the follow-up merely because results are few, generic, or incomplete.
+
+Write each query as one short natural-language question or intent statement, not a keyword list. Derive it from the user's retrieval goal instead of copying or concatenating nouns from the prompt. Follow the user's language for the prose while preserving exact code, API, path, workflow, and project identifiers. Retain at least one distinctive noun phrase from the user's wording as an anchor, together with any explicit negation, time/order, quantity, or scope qualifier. Also retain one stable task entity explicitly established by the current conversation or live code/documentation when it is needed to resolve that anchor or make the target decidable; do not drop it merely because it is absent from the newest fragmented user message. Do not replace an anchor or stable entity with a more abstract mechanism, a more specific implementation guess, or an unverified term. Preserve whether a retained detail is an observed symptom, desired outcome, disputed field or hypothesis, or explicit exclusion; do not turn an observation into a required invariant or replace a named disputed field with a generic reference.
 
-Write each query as one short natural-language question or intent statement, not a keyword list. Derive it from the user's retrieval goal instead of copying or concatenating nouns from the prompt. Follow the user's language for the prose while preserving exact code, API, path, workflow, and project identifiers. State what prior knowledge is needed and the relationship, decision, constraint, behavior, or risk being investigated. Include 2-5 stable exact identifiers when they are relevant and known, but integrate them grammatically instead of appending search tags or filler.
+Preserve the user's requested answer shape as well as the target: for example, whether a value was introduced by a prior code change, which failed experiments require rerun, how a negative case differs, what source boundary applies, or which existing plan remains current. Encode an explicit exclusion, source boundary, or qualifier such as only, previous, failed, negative, not, latest, or before/after when it changes the answer. Do not turn an imperative, URL, copied log, or full task request into the query verbatim; extract the smallest reusable historical fact that could change the next action. When the user explicitly names several independent deliverables and their respective historical facts could change different next actions, use the existing two-query allowance for complementary coverage: let the primary query cover the central implementation or decision, and let the complementary query cover the separate validation, artifact, reporting, or boundary question. Do not split one tightly coupled task or create a second query merely to enumerate every noun.
+
+State a fact-sized relationship that can change the next action: a target under a condition, and the decision, invariant, consequence, root cause, ownership, compatibility, validation question, or requested answer at issue. For behavior, data, and lifecycle work, every query must use this visible shape: `<target>: <condition>，<decision / invariant / consequence / validation question>?`. Keep the colon in both Chinese and English so the target, condition, and decision boundary remain explicit. Do not emit a generic topic, a keyword list, a label such as `primary query`, or an explanation around the query.
+
+For a complementary first-round pair, each query must stand alone and cover a different decision boundary. Use a complementary pair only when the provided context gives each decision boundary a distinct exact code, API, path, workflow, or project identifier; otherwise keep one focused combined query that preserves both user-stated facts. Do not merely restate the same question with synonyms. If the user describes only one tightly coupled decision, emit exactly one query. Use one or two stable exact identifiers when they sharpen the query, and integrate them grammatically instead of appending search tags or filler. Use only user-provided anchors and stable terms from live code or documentation; do not reconstruct unseen fact wording from recalled memory.
 
 Pass the query directly with `--query`. Put every dynamically generated query in single quotes, never double quotes. Treat `$HOME`, backticks, and `$(command)` as literal text inside those quotes. Replace each literal single quote in the value with the exact POSIX sequence `'\''`.
 
-For example:
+Use these actual output shapes as examples. They are queries themselves, not full user prompts or instructions for the user. Each Chinese/English pair is a language variant: choose the one matching the user, never run both merely because both are shown. The comments explain the example only and are not part of emitted query text.
 
 ```bash
-memorax-cli search --query 'What prior decisions define the memorax-code parser API failure boundary for malformed input?'
-memorax-cli search --query 'What prior review policies and regression risks apply to the memorax-code parser API cleanup boundary?'
-memorax-cli search --query 'memorax-code 中 Backend、Codex adapter 与 memory 层的职责如何衔接，之前为什么这样划分？'
+# One tightly coupled decision: emit one query.
+memorax-cli search --query 'Trace 生产版本：升级后到达的记录中，应以哪个客户端版本字段判断由旧插件产生，而非新版本上传进程？'
+memorax-cli search --query 'Trace producer version: after an upgrade, which client-version field shows that an event came from the old plugin rather than the new uploader?'
+
+# Two independent boundaries: emit a complementary pair.
+memorax-cli search --query '任务上下文：升级新包后已打开任务仍按旧提示，是否绑定旧版本且必须新开对话？'
+memorax-cli search --query '包缓存版本冲突：本地新包与缓存冲突时，已打开任务为何仍使用旧提示，如何确认实际加载版本？'
+memorax-cli search --query 'Task context after upgrade: can an already-open task keep old injected context, and must validation use a fresh task?'
+memorax-cli search --query 'Package-cache version collision: how do we confirm which version the active task actually loaded?'
+
+# Preserve an explicit lifecycle condition and the required invariant.
+memorax-cli search --query '自动写回：事件回调不等待 Promise 时，如何在消息终态后执行并防止重复？'
+memorax-cli search --query 'Automatic writeback: when an event callback does not await a Promise, how should it run after message terminal state without duplicates?'
+
+# Preserve a source boundary rather than turning it into a generic SDK question.
+memorax-cli search --query '桌面 SDK 数据权威：无原生命令行时，应从哪些规范化消息和会话生命周期事件获取数据？'
+memorax-cli search --query 'Desktop SDK authority: without a native CLI, which normalized messages and session lifecycle events are authoritative?'
 ```
 
 Keep queries under 25 words when practical for the language, but do not shorten them into ungrammatical fragments. Exclude secrets, private URLs, full prompts, raw transcripts, copied files, long logs, stack traces, and one-off task details.
 
-Read or summarize at most two relevant items. Prefer memories matching the current repository, module, API, lifecycle surface, ownership boundary, behavior, and failure mode. Treat verified memories as routing and validation hints, not patch recipes. Treat failed-attempt memories as negative evidence. Ignore stale or unrelated items and anything conflicting with current source, tests, or durable documentation.
+Do not use abstract query facets such as "state", "fix", "safety", or "best practice" unless they are the concrete target. Do not use generic security or safety queries as complementary queries; bind every query to an exact target, condition, and behavior boundary.
+
+Merge and deduplicate first-round results by item identity when available, otherwise by matching scope, condition, claim, and consequence. Accept a memory only when all three checks pass: it has the same component, API, workflow, or ownership boundary; it has the same behavior, symptom, condition, or change; and it supplies a condition, conclusion, consequence, fix, or validation idea that can change the current action. Read or summarize at most two accepted direct hits. Prefer memories matching the current repository, module, API, lifecycle surface, ownership boundary, behavior, and failure mode. Treat verified memories as routing and validation hints, not patch recipes. Treat failed-attempt memories as negative evidence. Ignore stale or unrelated items and anything conflicting with current source, tests, or durable documentation. For application questions, reject retrieval-strategy, evaluation, prompting, or workflow-process memories as domain evidence even if they repeat application terms. If no memory passes all three checks, say that memory is insufficient for the requested decision rather than filling the gap with a generic principle.
 
 ## Transport Failures
 

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/personal-read.md

@@ -39,7 +39,7 @@ python3 <skill-dir>/scripts/user_profile_memory.py list --repo <repo>
 
 Use only active preferences returned by the script. If the preferences file does not exist, report that no user-profile memory is available; the list operation does not create it.
 
-Mention only preferences relevant to the current request unless the user explicitly asks to list all of them. Stored preferences describe how Codex should interact with the user; they are not repository facts.
+Mention only preferences relevant to the current request unless the user explicitly asks to list all of them. Stored preferences describe how the coding agent should interact with the user; they are not repository facts.
 
 ## Priority
 

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/personal-write.md

@@ -21,27 +21,36 @@ Before writing, ensure the repository root `.gitignore` contains `.repo_memory/`
 
 Do not create a global procedures file, index, event log, generated metadata, or version history. Do not edit `.repo_memory/PROFILE.md`, `.repo_memory/resources/`, `.repo_memory/raw/`, or `.repo_memory/user-profile/`.
 
-Choose the closest existing topic file. Update it when the user refines the same procedure; create a new file only for a distinct topic. Remove superseded wording rather than preserving old versions.
+Choose the closest existing topic file before writing:
+
+- New topic: create a file.
+- Addition or refinement to the same topic: update the existing file.
+- A new rule directly conflicts with or replaces an old rule: update the existing file and remove the superseded content.
+- An old rule references a command, file, or workflow that no longer exists: update the invalid part; delete the file if the entire procedure is obsolete.
+- Equivalent content: do not add a duplicate.
+- If it is unclear whether the change is durable or only applies to the current task: ask the user.
+
+Do not modify existing memory because of a one-time instruction for the current task. Do not scan or clean up unrelated topics.
 
 Use this shape when useful:
 
 ```markdown
-# 代码审查
+# Reviewing Code
 
-Use when: 审查当前仓库中的代码变更时。
+Use when: reviewing changes in this repository.
 
 ## Procedure
 
-1. 创建 PR 前先审查变更。
-2. 解决阻塞性问题。
-3. 审查完成后再创建 PR。
+1. Review the changes before creating a PR.
+2. Resolve blocking findings.
+3. Create the PR only after review is complete.
 
 ## Exceptions
 
-- 优先遵循用户当前提出的更具体指令。
+- Follow a more specific current user instruction first.
 ```
 
-Delete only the topic file or section the user explicitly identifies. Do not retain deleted text in tombstones, backups, inactive entries, or history files.
+Delete only the topic file, section, or step the user explicitly identifies, and preserve unrelated content. Do not retain deleted text in tombstones, backups, inactive entries, or history files. Apply the same rule to superseded text.
 
 ## User-Profile Memory
 
@@ -59,15 +68,26 @@ List existing preferences before adding and perform semantic matching:
 python3 <skill-dir>/scripts/user_profile_memory.py list --repo <repo>
 ```
 
-If equivalent content exists, do not add it again. Update the matching id when an existing entry expresses the same preference differently. Add only a genuinely new preference:
+Handle the semantic match before writing:
+
+- New preference: add a new preference.
+- Equivalent content: do not add a duplicate.
+- Addition or refinement to the same preference: update the existing preference.
+- A new preference directly conflicts with or replaces an old preference in the same scope: update the existing id and remove the superseded content.
+- The user explicitly says a preference no longer applies: delete that preference.
+- Its `Applies when` environment, tool, or workflow no longer exists: update the scope; delete it if the entire preference is obsolete.
+
+Do not modify or delete existing preferences because of a one-time instruction for the current task. Do not scan or clean up unrelated preferences.
+
+Use the matching id for updates. Add only a genuinely new preference:
 
 ```bash
 python3 <skill-dir>/scripts/user_profile_memory.py add \
   --repo <repo> \
   --type communication \
-  --description "用户希望在当前仓库中使用简洁的中文回答。" \
-  --applies-when "回答当前仓库相关问题时。" \
-  --do-not-apply-when "用户明确要求使用其他语言或格式。"
+  --description "User prefers concise Chinese answers for this repository." \
+  --applies-when "Answering questions in this repository." \
+  --do-not-apply-when "The user explicitly requests another language or format."
 ```
 
 Allowed script types are `communication`, `workflow`, `environment`, and `profile`. These type names do not expand this authority: never use `workflow` or `environment` to store an executable repository procedure.
@@ -83,7 +103,7 @@ python3 <skill-dir>/scripts/user_profile_memory.py update \
   --do-not-apply-when <exception>
 ```
 
-If multiple preferences may match, ask the user to choose before updating. Delete only an explicitly identified preference:
+If multiple preferences may match, or it is unclear whether the change is durable, ask the user. Delete only an explicitly identified preference:
 
 ```bash
 python3 <skill-dir>/scripts/user_profile_memory.py delete \

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/repo-build.md

@@ -15,6 +15,7 @@ The user selects a repository, not a memory directory. Do not ask for a `.repo_m
 ```text
 <repo>/.repo_memory/
 ├── PROFILE.md
+├── <repo-native-topic>.md conceptual pages
 ├── raw/
 │   ├── prepare-report.json
 │   ├── git-commits.json
@@ -25,10 +26,35 @@ The user selects a repository, not a memory directory. Do not ask for a `.repo_m
     └── issues.md
 ```
 
-Script-generated artifacts: `raw/prepare-report.json`, `raw/git-commits.json`, and optional `raw/github-facets.json` or `raw/gitlab-facets.json`. Agent-authored durable artifacts: `PROFILE.md`, `resources/commits.md`, `resources/prs.md`, and `resources/issues.md`.
+Script-generated artifacts: `raw/prepare-report.json`, `raw/git-commits.json`, and optional `raw/github-facets.json` or `raw/gitlab-facets.json`. Agent-authored durable artifacts: `PROFILE.md`, repository-native supporting conceptual pages when the repository has enough surface area, `resources/commits.md`, `resources/prs.md`, and `resources/issues.md`. Temporary planning artifact `.repo_memory/_plan.md` is allowed during drafting but must be removed before final validation.
 
 User-managed sidecars may coexist under `.repo_memory/procedure-memory/` and `.repo_memory/user-profile/`. Builder scripts preserve them and exclude them from bundle validation; this skill must not create, edit, or summarize their contents as repo-memory evidence.
 
+## Wiki-Style Output Contract
+
+MemoraX repo memory is a wiki-style repository memory backed by raw mechanical evidence. The primary user-facing product is a readable wiki, not a dense schema dump or a history table.
+
+- `PROFILE.md` is the only fixed conceptual wiki file and the wiki landing page: project identity, what the repo contains, how it works, first-use path, Major Areas, Supporting Pages, provider context, and evidence inspected.
+- Do not assume fixed supporting page names. Decide supporting pages and filenames from the repository itself after discovery.
+- For very small repositories, `PROFILE.md` plus 1-2 supporting pages is enough. For most repositories, generate 3-7 Markdown pages total, including `PROFILE.md`. Only exceed 7 pages when the repository clearly has multiple substantial, independent areas that would become confusing if merged.
+- Every durable supporting conceptual page must include frontmatter with `schema: "repo_memory_wiki_page.v0.1"` so validation can scan it.
+- Supporting pages explain concepts, workflows, system areas, change surfaces, setup, verification, and agent routing cautions. They must link claims to inspected docs/source and use conservative wording when lightweight mode did not inspect source.
+- resources/*.md remain compact historical routing cards for commits, PRs/MRs, and issues. They should not be the main architecture explanation.
+- Keep raw JSON as debug evidence only. Do not ask future agents to read raw facets unless compact pages and resources are insufficient.
+
+## Conceptual Page Planning
+
+After discovery and before final wiki writing, create a temporary planning artifact at `.repo_memory/_plan.md`. Keep it compact. Use it to outline intended final pages, each page purpose, source evidence, page boundaries, canonical homes for overlapping concepts, remaining questions, weak evidence, and paths that must be verified before final writing.
+
+- Remove `.repo_memory/_plan.md` before final validation; it is not part of the durable repo memory bundle.
+- Organize pages like human documentation, not a raw file inventory. Use human documentation titles. Do not title pages or headings after source paths, and do not mirror the source tree.
+- Create a page only when a future human or agent needs a canonical explanation for a concept, workflow, system area, or change surface. A page is a durable orientation artifact, not a parking place for exploration facts.
+- Merge rather than split when two pages would repeat the same workflow, types, or source paths; when one page would only explain a subset of another page; or when the distinction is based on source directory layout rather than reader task or concept.
+- Split rather than merge when one page would mix unrelated reader tasks; when a concept has its own workflow, data model, risks, and source-backed change guidance; or when a page would become too long to navigate.
+- Prefer headings inside broader pages before creating many small pages. Avoid thin pages and stub-like pages.
+
+Natural documentation domains are candidates, not a required checklist: architecture, workflows, data model, integrations, operations, testing/evaluation, and extension points. In `_plan.md`, decide which candidates were selected, merged, or skipped and why. Generic names such as `architecture.md`, `runtime-flow.md`, and `developer-workflow.md` are fallback names only when repository vocabulary gives no stronger topic.
+
 ## Repository Prerequisite
 
 The selected target must be a local git repository: either the directory contains `.git/` or is inside a git worktree. A GitHub/GitLab remote is optional; local-only git repositories are supported.
@@ -60,19 +86,38 @@ Default mechanical collection settings are intentionally visible in `<skill-dir>
 
 ```json
 {
-  "schema": "repo_memory_builder_defaults.v1",
-  "limits": {
-    "commits": 30,
-    "prs": 30,
-    "issues": 30
+  "schema": "repo_memory_builder_defaults.v2",
+  "repoHistory": {
+    "mode": "provider",
+    "limits": {
+      "commits": 30,
+      "prs": 30,
+      "issues": 30
+    }
   },
   "summaryChars": 4000
 }
 ```
 
-To change defaults for future builder runs, edit `defaults.json`, not the Python scripts. To override one run, pass `--commit-limit`, `--pr-limit`, `--issue-limit`, or `--summary-chars` to `collect_all.py`.
+To change defaults for future builder runs, edit `defaults.json`, not the Python scripts. To override one run, pass `--history-mode`, `--commit-limit`, `--pr-limit`, `--issue-limit`, or `--summary-chars` to `collect_all.py`.
+
+Provider collection is best-effort by default. Use `--history-mode local-only` or `--skip-provider` for an explicit local-only run that does not call GitHub/GitLab, and use `--history-mode provider-required` or `--require-provider` only when the user explicitly requires PR/MR/issue evidence and the run should fail instead of falling back to local-only memory.
+
+## Historical Evidence Policy
+
+Historical evidence collection is configurable per run with `--history-mode` and by default with `repoHistory.mode` in `defaults.json`:
+
+| Mode | Commits | PRs/MRs and issues | Resource file contract |
+|------|---------|--------------------|------------------------|
+| `--history-mode none` | Disabled | Disabled | Write disabled resource files for commits, PRs/MRs, and issues using `source: "history_disabled"`, `resource_count: 0`, and `raw_source: ""`. |
+| `--history-mode commits-only` | Collected locally | Disabled | Write commit resources from `raw/git-commits.json`; write PR/issue files using `source: "provider_skipped_local_only"`, `resource_count: 0`, and `raw_source: ""`. |
+| `--history-mode local-only` | Collected locally | Disabled | Same as commits-only; use when the user wants local Git history but no provider calls. |
+| `--history-mode provider` | Collected locally | Best-effort | Default. Collect provider facets when ready; if provider evidence is unavailable or fails, continue local-only and mark PR/issue resources unavailable. |
+| `--history-mode provider-required` | Collected locally | Required | Fail the collection if provider facets cannot be collected. Use only when the user explicitly requires PR/MR/issue evidence. |
+
+`--skip-provider` is a compatibility alias for `--history-mode local-only`; `--require-provider` is a compatibility alias for `--history-mode provider-required`.
 
-Provider collection is best-effort by default. Use `--skip-provider` for an explicit local-only run that does not call GitHub/GitLab, and use `--require-provider` only when the user explicitly requires PR/MR/issue evidence and the run should fail instead of falling back to local-only memory.
+When history or provider evidence is disabled, skipped, unavailable, or degraded, still create `resources/commits.md`, `resources/prs.md`, and `resources/issues.md`; write disabled resource files for any historical channel that was not collected. The disabled or unavailable resource files tell future agents that the builder intentionally did not collect that evidence. For PR/issue files, do not say that no PRs or issues exist unless provider evidence was actually collected and empty.
 
 ## User Count Requests
 
@@ -150,7 +195,7 @@ Do not use a restricted shell sandbox to verify provider/API availability. Verif
 
 ### `scripts/validate_memory.py`
 
-Use this as the final gate after authoring `PROFILE.md` and `resources/*.md`. It accepts either the repository root or the memory root, validates required files, JSON parseability, frontmatter counts, placeholder removal, and provider raw/resource consistency.
+Use this as the final gate after authoring `PROFILE.md`, supporting conceptual pages, and `resources/*.md`. It accepts either the repository root or the memory root, validates required files, JSON parseability, frontmatter counts, placeholder removal, and provider raw/resource consistency.
 
 ```bash
 python3 <skill-dir>/scripts/validate_memory.py <repo-path> --pretty
@@ -200,9 +245,12 @@ Run: `<notice.command>`
    - Form project-level understanding before looking at PR/issue history.
    - Record whether conclusions are doc-derived or code-inspected.
 
-4. **Draft `PROFILE.md`**
+4. **Plan and draft the wiki landing page and conceptual pages**
    - Read [repo-templates.md](repo-templates.md) before writing memory files.
-   - Include repo identity, checkout state, evidence inspected, agent consumption rules, module map, verification gates, architecture boundaries, resource pointers, and retrieval flow.
+   - Create `.repo_memory/_plan.md` after discovery and before final wiki writing. Use it to cluster repository-native conceptual areas, page purposes, evidence, boundaries, canonical homes, merge/split decisions, weak evidence, and path verification needs.
+   - Write `PROFILE.md` as the wiki landing page with repo identity, checkout state, what the repo contains, how it works, first-use path, Major Areas, Supporting Pages, provider context, and evidence inspected.
+   - Create repository-native supporting conceptual pages from the plan. Cover only concepts, workflows, system areas, or change surfaces with enough evidence to deserve canonical pages.
+   - Remove `.repo_memory/_plan.md` before final validation.
    - Record the selected build mode and avoid overstating code-level claims in lightweight mode.
 
 5. **Review raw evidence**
@@ -243,8 +291,9 @@ Every description must say what the item explains, when a future agent should op
 
 Generate memory that the `memorax-code` repo-read operation can consume progressively:
 
-- `PROFILE.md` is the stable entry point and should summarize identity, evidence, architecture, verification gates, and resource pointers.
-- `resources/*.md` are compact human-readable routing resources with search-grade descriptions.
+- `PROFILE.md` is the stable wiki landing page and should summarize identity, evidence, major areas, supporting pages, verification gates, and resource pointers.
+- Supporting conceptual pages are repository-native canonical homes for concepts, workflows, system areas, and change surfaces selected through temporary planning.
+- `resources/*.md` are compact historical routing cards with search-grade descriptions.
 - `raw/*.json` contains optional build/debug evidence for deep inspection when compact resources are insufficient.
 
 Do not duplicate the daily retrieval workflow here. The `repo-read` operation owns trigger timing, silent background-maintenance handoff, and task-specific search behavior.

package/lib/memorax-code-codex-adapter/skills/memorax-code/references/repo-read.md

@@ -2,7 +2,7 @@
 
 ## Role And Demand Gate
 
-Use existing `.repo_memory/` as a routing layer for repository identity, architecture, history, PR/issue context, remembered fixes, and cross-module search. Live code and tests remain authoritative.
+Use existing `.repo_memory/` as wiki-style repo memory for repository identity, architecture, history, PR/issue context, remembered fixes, and cross-module search. Live code and tests remain authoritative.
 
 Select this reference for broad repo introduction, history, architecture background, cross-module routing, PR/issue context, design rationale, or stale-memory awareness. Skip this reference for narrow tasks with a clear live-code target.
 
@@ -36,21 +36,27 @@ The default policy remains `adaptive(5 commits OR 24 hours)`. A missing or non-a
 
 ## Retrieval
 
-If `.repo_memory/PROFILE.md` is a readable regular file, read it once. Treat its descriptions as routing cues, not proof.
+If `.repo_memory/PROFILE.md` is a readable regular file, read `PROFILE.md` as the wiki landing page once. Treat its descriptions as routing cues, not proof.
 
-Search `PROFILE.md` and `.repo_memory/resources/` with a combined query built from the user's strongest handles: path, basename, symbol, command, PR/issue number, error text, module, branch, environment variable, or config key.
+Extract task-relevant links from `Major Areas` and `Supporting Pages`. Do not assume fixed page names; use `PROFILE.md` links and headings to find the repository-native canonical homes for the user's task. Open at most 2-4 relevant conceptual pages from `.repo_memory/*.md` before searching historical resources.
+
+Search `PROFILE.md`, `.repo_memory/*.md`, and `.repo_memory/resources/` with a combined query built from the user's strongest handles: path, basename, symbol, command, PR/issue number, error text, module, branch, environment variable, or config key.
 
 ```bash
 rg -n '<handle-1>|<handle-2>' \
-  .repo_memory/PROFILE.md .repo_memory/resources
+  .repo_memory/PROFILE.md .repo_memory/*.md .repo_memory/resources
 ```
 
 Use:
 
+- conceptual `.repo_memory/*.md` pages for repository-native canonical homes, workflows, system areas, change surfaces, and verification routing;
+- resources/*.md for historical routing cards;
 - `resources/commits.md` for local history and regressions;
 - `resources/prs.md` for merged or active implementation context;
 - `resources/issues.md` for symptoms, requests, and requirements.
 
+Disabled and unavailable historical resource files are collection state, not repository state. If a resource frontmatter uses `source: "history_disabled"`, `source: "provider_skipped_local_only"`, or `source: "provider_unavailable"` with `resource_count: 0`, do not conclude that there are no commits, PRs, MRs, or issues. Treat the channel as intentionally uncollected or unavailable; answer from available memory only. Ask whether to rebuild with provider history when that context matters.
+
 If a read is missing, unreadable, or structurally mixed, discard conclusions that depend only on the bundle. Do not repair it in the foreground.
 
 ## Retrieval Budget
@@ -58,6 +64,7 @@ If a read is missing, unreadable, or structurally mixed, discard conclusions tha
 - Read `PROFILE.md` at most once.
 - Run at most 2 combined `rg` commands.
 - Stop repo-memory retrieval as soon as the hits are sufficient.
+- Open at most 2-4 relevant conceptual pages total during the bounded memory phase.
 - Open only the matched resource section when `rg` context is insufficient.
 
 Do NOT open these unless the user explicitly asks or a compact hit contains only a `facetId`: