@memorax/memorax-code 0.1.11 → 0.1.12

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

@@ -0,0 +1,106 @@
+# 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. 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
+
+Select the executable before constructing any Search command. In Windows PowerShell, use `memorax-cli.cmd`; on macOS and Linux, use `memorax-cli`. Never invoke `memorax-cli.ps1`. Never run `Set-ExecutionPolicy` or otherwise change PowerShell execution policy for MemoraX commands. If an unqualified Windows invocation is blocked before the CLI starts with `UnauthorizedAccess` or `PSSecurityException`, retry the same command once with `memorax-cli.cmd`, preserving all arguments, the active workspace, and environment variables.
+
+Run the CLI from the active task workspace. The installed Hook and session binding supply the authoritative workspace root; do not run `git rev-parse`, infer the root from Git metadata, or substitute an unrelated working directory. Do not make `memorax-cli status` a mandatory preflight; use it only to diagnose a configuration or scope failure.
+
+Coding memory uses `<MemoraX base username>@<normalized repository name>` for Git workspaces and the normalized folder name for genuine non-Git directories. MemoraX Code resolves `.git`, `gitdir`, and `commondir` without executing Git. Linked worktrees share one repository scope; another clone, repository, or non-Git directory retains a different local session key even when its readable name matches.
+
+If a successful Search result reports `workspaceScopeFallbackReason: git_metadata_invalid`, malformed or incomplete metadata inside a direct `.git` directory was downgraded to the normalized local folder scope. Search has already run with the reported `effectiveUserId`. Present its `userNotice` once without pausing the current task or asking the user to repair Git first, then continue with the returned memory and live evidence. After the repository or `.git` metadata is repaired, later Search, Add, and automatic writeback in the same client session automatically use the restored Git repository scope.
+
+Require a readable active workspace binding. A CLI command from a linked worktree of the bound repository is valid. If `memorax-cli search` reports `workspace_scope_mismatch` or `workspace_scope_unavailable`, do not bypass the scope or fall back to an unscoped username. Do not change the CLI working directory and retry. Tell the user that memory search was not executed and no request was sent to MemoraX, then present the CLI's `userAction` in natural language. Continue the current task using only live code and documentation.
+
+If the selected platform command is not on `PATH`, or memory is disabled, unconfigured, or unavailable, report that briefly and continue with live code or documentation. Authenticate through MemoraX Code configuration; never recover credentials from shell history or place tokens in prompts. Treat injected memory as a hypothesis and verify it against the current checkout.
+
+## Search Decision
+
+Search when prior coding memory may change localization, implementation, review, validation, or explanation. Typical triggers include:
+
+- 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. 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:
+
+- **Development:** implementation, debugging, refactoring, test repair, build failures, feature work, API design, or migration planning.
+- **Review:** diff, commit, PR, patch, audit, risk assessment, or review-comment handling.
+- **Understanding:** implementation location, module explanation, architecture rationale, or repository comprehension when repo memory is not the requested authority.
+
+If the user asks for commit, PR, MR, issue, or repository architecture evidence, return to `SKILL.md` and route to repo memory instead.
+
+## Query Workflow
+
+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.
+
+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. Apply the escaping rule for the active shell:
+
+- Windows PowerShell: single quotes keep `$HOME`, backticks, and `$(command)` literal. Replace each literal single quote in the value with two single quotes (`''`); for example, `don't` becomes `'don''t'`.
+- macOS and Linux: Treat `$HOME`, backticks, and `$(command)` as literal text inside the quotes. Replace each literal single quote in the value with the exact POSIX sequence `'\''`.
+
+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.
+
+On Windows PowerShell, the first example must be invoked as:
+
+```powershell
+memorax-cli.cmd search --query 'Trace 生产版本：升级后到达的记录中，应以哪个客户端版本字段判断由旧插件产生，而非新版本上传进程？'
+```
+
+On macOS and Linux, use the `memorax-cli search` forms below. For other Windows examples, preserve every argument but replace the leading executable with `memorax-cli.cmd`.
+
+```bash
+# 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.
+
+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
+
+If search fails with `fetch failed`, `This operation was aborted`, a timeout, DNS failure, `ENOTFOUND`, `EAI_AGAIN`, or a similar transport or sandbox error, retry the same `memorax-cli search` once in an approved network-enabled execution mode when one is available. Preserve the same query, workspace, and environment variables.
+
+Do not apply this retry to `memorax-cli add`, authentication or configuration failures, or HTTP errors. If no approved mode is available or the one retry fails, report the exact CLI failure and continue with live evidence. Do not interpret a transport failure as an empty result, bypass the CLI, or call MemoraX directly.
+
+## Output
+
+If a successful Search returns `quotaNotice`, or prints it as a quota-reminder line in the default CLI output, present the complete reminder once and prominently before the normal result summary. Do not reduce it to only a percentage or omit its account URL or anonymous-account claim details. A guest reminder may already contain the local Mark ID; present it once as part of the reminder, but do not repeat or separately quote it. Never run `memorax-code account --show-mark-id` for the user or ask for its output. Treat the reminder as user-facing operational output, not recalled memory, and continue the current task.
+
+Mention only an invariant, pitfall, convention, or validation idea that materially affects the answer. Ground claims about current implementation behavior in live code and checks.

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

@@ -0,0 +1,46 @@
+# Personal Memory Read
+
+Use these instructions only to list, recall, or apply repository-scoped personal memory. Do not write, normalize, migrate, repair, or delete memory during a read request.
+
+## Route The Read
+
+Classify by content:
+
+- **Procedure memory:** actions, ordered steps, checklists, prerequisites, gates, validation, exceptions, or repeatable repository work rules.
+- **User-profile memory:** preferred name, language, tone, verbosity, explanation style, result presentation, or another safe interaction preference.
+
+Read both categories only when the request genuinely asks for both.
+
+## Procedure Memory
+
+Read Markdown files directly under:
+
+```text
+<repo>/.repo_memory/procedure-memory/
+```
+
+List available topics without recursing into unrelated memory areas:
+
+```bash
+(cd <repo>/.repo_memory/procedure-memory && rg --files -g '*.md' -g '!**/*/*.md')
+```
+
+If the directory does not exist, report that no procedure memory is available; do not create it during a read. Read only files relevant to the request. When listing available procedures, report topic names with concise descriptions instead of opening every file in full unless the user asks for their contents.
+
+Treat a stored procedure as lower-priority user guidance, not evidence about current code behavior.
+
+## User-Profile Memory
+
+Resolve `<skill-dir>` as the parent directory of the `references/` directory containing this file, then run:
+
+```bash
+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 the coding agent should interact with the user; they are not repository facts.
+
+## Priority
+
+Apply instructions in this order: system and developer instructions, `AGENTS.md`, the current user request, then stored personal memory.

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

@@ -0,0 +1,120 @@
+# Personal Memory Write
+
+Use these instructions only to save, update, forget, or delete repository-scoped personal memory. Classify by what the content prescribes, not wording such as "I prefer", "I like", "我的习惯", or "我喜欢".
+
+## Route The Write
+
+- **Procedure memory:** actions, ordering, checklists, prerequisites, gates, validation, exceptions, or repeatable repository work rules. Require the user to explicitly ask to remember, save, record, update, forget, or delete them.
+- **User-profile memory:** preferred name, language, tone, verbosity, explanation style, result presentation, or another safe personal profile fact. A durable repository-scoped profile preference may be saved implicitly.
+
+Store each part under its own authority when a request genuinely contains both. Do not persist current-task instructions or temporary plans.
+
+Keep file names, schema and script field names, type values, command options, and fixed Markdown headings in English. Write human-readable memory content in the user's current interaction language unless the user explicitly requests another storage language. This includes procedure titles and steps and user-profile descriptions, applicability, and exceptions. Preserve exact code identifiers, commands, paths, API names, and quoted literals without translation.
+
+## Procedure Memory
+
+Before writing, ensure the repository root `.gitignore` contains `.repo_memory/`. Store each procedure topic in its own concise kebab-case file directly under:
+
+```text
+<repo>/.repo_memory/procedure-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 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: reviewing changes in this repository.
+
+## Procedure
+
+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, 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
+
+Use only:
+
+```text
+<repo>/.repo_memory/user-profile/preferences.md
+```
+
+Resolve `<skill-dir>` as the parent directory of the `references/` directory containing this file. The script owns directory creation, `.gitignore` updates, parsing, normalization, locking, duplicate detection, counts, and deterministic rewriting. Do not hand-edit `preferences.md` except when diagnosing a script failure.
+
+List existing preferences before adding and perform semantic matching:
+
+```bash
+python3 <skill-dir>/scripts/user_profile_memory.py list --repo <repo>
+```
+
+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 "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.
+
+Update a clearly identified preference in place:
+
+```bash
+python3 <skill-dir>/scripts/user_profile_memory.py update \
+  --repo <repo> \
+  --id <preference-id> \
+  --description <current-description> \
+  --applies-when <current-scope> \
+  --do-not-apply-when <exception>
+```
+
+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 \
+  --repo <repo> \
+  --id <preference-id>
+```
+
+For delete-all requests, list active preferences and delete each id. Do not preserve deleted text elsewhere.
+
+## Safety And Output
+
+Do not store secrets, tokens, credentials, `.env` content, sensitive personal data, repository facts, code history, design rationale, one-off task details, raw transcripts, hidden tests, exact patches, raw diffs, target commits, or unsafe destructive commands.
+
+After a successful write, update, or deletion, identify the affected topic or preference briefly and confirm that it is local to the current repository.

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

@@ -0,0 +1,319 @@
+# Repo Memory Build
+
+## Core Principle
+
+The agent authors the repo memory. Scripts collect and validate mechanical evidence, but do not replace agent-authored memory.
+
+Do not let a script write `PROFILE.md`, `resources/commits.md`, `resources/prs.md`, or `resources/issues.md`. The agent must inspect the local project, understand the code, and author the human-facing memory. Scripts may create deterministic raw evidence only.
+
+This is the full-build operation, not the daily reader or incremental updater. Return to `SKILL.md` and use `repo-read.md` for task-time search over existing memory. For latest-change-only updates to an existing `.repo_memory`, use `repo-update.md`. Use this reference for first-time creation, full rebuilds, or full refreshes that recollect raw evidence and rewrite authored memory.
+
+## Output Layout
+
+The user selects a repository, not a memory directory. Do not ask for a `.repo_memory` path. Create this bundle inside the target repository:
+
+```text
+<repo>/.repo_memory/
+├── PROFILE.md
+├── <repo-native-topic>.md conceptual pages
+├── raw/
+│   ├── prepare-report.json
+│   ├── git-commits.json
+│   └── github-facets.json or gitlab-facets.json
+└── resources/
+    ├── commits.md
+    ├── prs.md
+    └── 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.
+
+If the directory is not a git repository, do not create `.repo_memory/` and do not fabricate a memory bundle from file inspection alone. Stop with a prominent notice:
+
+```text
+**Repo Memory Cannot Be Built Yet**
+
+> This folder is not a git repository, so repo memory cannot collect local commit history or provider-linked PR/MR/issue evidence.
+
+**Next steps**
+- If this is an existing project, open the real cloned repo directory.
+- If this is a new project, run `git init` first, make at least one commit, then rerun the `repo-build` operation.
+- If you only want file inspection, continue by inspecting files without repo memory.
+```
+
+## Path Convention
+
+`<skill-dir>` means the parent directory of the `references/` directory containing this file. Resolve it before running scripts, for example:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --pretty --progress
+```
+
+## Default Settings
+
+Default mechanical collection settings are intentionally visible in `<skill-dir>/defaults.json`:
+
+```json
+{
+  "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 `--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`.
+
+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
+
+If the user mentions how many commits, PRs/MRs, or issues to collect, treat that as a one-run override and pass explicit limit flags to `collect_all.py`. Do not edit `defaults.json` for a one-run request.
+
+Examples:
+
+- "拉 50 条 commit" means add `--commit-limit 50`.
+- "PR 拉 20 条，issue 拉 30 条" means add `--pr-limit 20 --issue-limit 30`.
+- "commit、PR、issue 都拉 50 条" means add `--commit-limit 50 --pr-limit 50 --issue-limit 50`.
+
+Only edit `defaults.json` when the user asks to change defaults for future build runs, for example "以后默认都拉 50 条" or "把 repo memory 的默认 limit 改成 50".
+
+## Progress Display
+
+Skill instructions cannot render app-native progress components by themselves. For interactive builder runs, prefer `collect_all.py --progress`; it renders a terminal progress bar on stderr while keeping stdout as the final JSON report. Omit `--progress` only for strict machine-only runs that must avoid stderr progress output.
+
+The progress bar covers the mechanical collection steps: preparation, local commits, and provider facets. Provider warnings are not terminal notifications; they are returned in the JSON report as structured `notices[]` so the agent can show them as a normal user-visible assistant message. The progress bar does not replace the required provider warning notice, final JSON report review, agent-authored Markdown work, or final validation.
+
+## Build Modes
+
+Build mode controls only the local project understanding phase. The mechanical collection, authoring, and validation flow stays the same.
+
+- Default to lightweight mode when the user does not specify.
+- Use lightweight mode for a quick or docs-only pass. Read root README/high-level docs, repo-local agent instructions such as `AGENTS.md` or `CLAUDE.md`, and clearly linked overview/setup docs. Do not inspect source, manifests, scripts, or CI just to deepen the profile. Mark code-level architecture claims as doc-derived or unverified.
+- Use deep mode only when the user explicitly asks for deep/thorough/full work, or when docs are too thin to produce useful memory. Read docs and agent instructions, then inspect repository structure, module READMEs, representative source and entrypoints, manifests, scripts, and CI before writing `PROFILE.md`.
+- Do not stop to ask for a mode unless the user's request is contradictory.
+
+## Tool Roles
+
+### `scripts/collect_all.py`
+
+Use this as the primary mechanical path. It prepares the workspace, collects local git commit evidence, collects GitHub/GitLab PR/MR/issue evidence when provider auth is ready, and returns a JSON report describing completed steps and outputs. If provider collection fails after preparation reports `provider_evidence_state: "ready"`, the default behavior is to keep local commit evidence, emit a warning notice, and report `steps.provider_facets.degraded_to_local_only: true`. Only `--require-provider` turns this into a hard failure.
+
+Default run:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --pretty --progress
+```
+
+One-run limit override:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --commit-limit 50 --pr-limit 20 --issue-limit 20 --pretty --progress
+```
+
+Full refresh of an existing `.repo_memory` bundle:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --reuse --snapshot-ref HEAD --pretty --progress
+```
+
+Local-only memory or hard-required provider evidence:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --skip-provider --pretty --progress
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --snapshot-ref HEAD --require-provider --pretty --progress
+```
+
+Tell the user before starting long collection steps. After completion, report collected counts from the JSON report: local commits, PRs/MRs, issues, provider state, skipped steps, notices, and output files.
+
+#### Final Summary Notices
+
+If the final JSON report contains `notices[]`, the final user-facing summary must include those notices explicitly. Include the notice title, message, and next steps, especially `Provider Evidence Unavailable`.
+
+Do not silently collapse notices into counts, provider state, or a generic "local-only" sentence. If provider evidence degraded to local-only, say that directly and include the reason from the notice.
+
+#### Provider Sandbox and Transport Failures
+
+`gh/glab` provider collection needs external network access. If provider stderr or `notices[]` shows `fetch failed`, timeout, DNS, connection, TLS, `ENOTFOUND`, `EAI_AGAIN`, or similar transport text, report provider evidence unavailable and continue local-only unless `--require-provider` was requested.
+
+Verify provider authentication in the same normal shell with the command reported by `collect_all.py`; for GitHub Enterprise or self-hosted GitLab this may include `--hostname <host>`. Authenticate with `gh auth login` or `glab auth login` (also host-scoped when prompted), then rerun `collect_all.py`; do not paste tokens into the skill or call provider APIs directly.
+
+Do not use a restricted shell sandbox to verify provider/API availability. Verify in a normal shell or approved network-enabled mode. If only restricted shell access is available, report provider evidence unavailable and continue local-only unless `--require-provider` was requested. Do not treat a provider transport failure as empty PR/issue evidence, no PR/issue changes, bad login, or bypass the scripts with direct APIs, browser scraping, copied credentials, or hand-written raw facets.
+
+### `scripts/validate_memory.py`
+
+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
+```
+
+### Internal scripts
+
+These are invoked by `collect_all.py`. Use them directly only for debugging or narrow recovery:
+
+- `prepare_repo_memory.py`: validates the target repo, handles `--reuse`, creates `.repo_memory/{raw,resources}`, updates `.gitignore`, and writes `raw/prepare-report.json`.
+- `git_commit_facets.py`: collects local commit facets from the selected snapshot. It needs only local git history.
+- `github_resource_facets.py` and `gitlab_resource_facets.py`: collect provider PR/MR/issue facets when `prepare-report.json` says the provider is ready. They share the same downstream resource shape; GitLab merge requests are normalized into PR resources.
+
+Provider resource facets share this contract: `--snapshot-ref HEAD` filters merged PRs/MRs by merge-commit ancestry against the local snapshot; open and closed-unmerged PRs/MRs are not retained as landed evidence; issues come from the current bounded provider list because issues do not have reliable commit ancestry. For PRs/MRs, `--pr-limit` is the retained count after snapshot filtering.
+
+## Agent Workflow
+
+Follow this order manually:
+
+1. **Collect mechanical evidence**
+   - Run `collect_all.py`.
+   - Use `--reuse` only for a full refresh/rebuild of an existing `.repo_memory`; for latest-change-only updates, prefer `repo-update.md`.
+   - Read the returned JSON report and `.repo_memory/raw/prepare-report.json`.
+   - Stop if preparation fails. Do not improvise around git/repo safety checks.
+
+2. **Show provider notices**
+   - If `notices[]` contains `Provider Evidence Unavailable`, show it as a normal assistant message before continuing and repeat it in the final summary.
+   - Render `title` as a bold heading, `message` as body text, `command` as the login command when present, and `next_steps` as recovery steps. Do not show raw JSON or put the notice inside a fenced code block.
+   - If `notices[]` is absent, fall back to `raw/prepare-report.json`: when `provider_notice_level` is `warning`, render `provider_notice_markdown` as a normal assistant message.
+   - If the user explicitly required PR/MR/issue evidence, run with `--require-provider`, stop after provider failure, and ask them to install/login or fix repository access before rerunning.
+
+Use this visible shape:
+
+```text
+**Provider Evidence Unavailable**
+
+<notice.message>
+
+**Next steps for provider evidence**
+Run: `<notice.command>`
+
+<notice.next_steps rerun item>
+```
+
+3. **Understand the local project**
+   - Choose lightweight by default; choose deep only when requested or clearly needed.
+   - Form project-level understanding before looking at PR/issue history.
+   - Record whether conclusions are doc-derived or code-inspected.
+
+4. **Plan and draft the wiki landing page and conceptual pages**
+   - Read [repo-templates.md](repo-templates.md) before writing memory files.
+   - 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**
+   - Confirm `raw/git-commits.json` exists.
+   - When provider evidence is available, confirm the matching provider facets exist.
+   - If provider evidence is missing, skipped, or degraded to local-only, keep PR/issue resources explicitly marked unavailable instead of inventing provider evidence.
+
+6. **Author human-readable resources**
+   - Use the resource templates in [repo-templates.md](repo-templates.md).
+   - Read raw facets and write `resources/commits.md`, `resources/prs.md`, and `resources/issues.md` yourself.
+   - Keep resources compact. Use one fixed-field section per commit, PR/MR, or issue, separated by `---`; do not use Markdown tables.
+   - Every section must include a search-grade `Description`.
+
+7. **Finalize and validate**
+   - Add final pointers and provider snapshot notes to `PROFILE.md`.
+   - Run `validate_memory.py` as the final gate.
+   - Fix authored Markdown placeholders, frontmatter counts, or resource mismatches before reporting success.
+
+## Refresh/Update Workflow
+
+For incremental updates to recent commits, PRs/MRs, or issues in an existing `.repo_memory`, use `repo-update.md`.
+
+Use builder refresh only when the user wants a full rebuild/full refresh while preserving the existing memory directory:
+
+```bash
+python3 <skill-dir>/scripts/collect_all.py --repo-path <repo-path> --reuse --pretty --progress
+```
+
+Then rewrite affected human-authored resources from the new raw evidence. Preserve useful existing notes only when they are still supported by current raw evidence and live repository inspection. Never append or patch raw/provider JSON by hand; rerun the collection scripts instead.
+
+## Description Quality Standard
+
+`Description` is the main agentic-search surface for `resources/commits.md`, `resources/prs.md`, and `resources/issues.md`. Keep only the core rule here; the full quality standard and section scaffolding live in [repo-templates.md](repo-templates.md).
+
+Every description must say what the item explains, when a future agent should open it, which modules/files/commands/config it points to, concrete search cues, and evidence strength. Do not copy raw summaries, headings, or tables into descriptions, and avoid vague descriptions like "fix bug" or "update docs".
+
+## Generated Knowledge Contract
+
+Generate memory that the `memorax-code` repo-read operation can consume progressively:
+
+- `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.
+
+## Trust Rules
+
+- Local code and targeted verification are stronger evidence than generated memory.
+- Local git commit evidence is checkout history and does not require provider login.
+- GitHub/GitLab PR/issue evidence is historical/contextual, not proof of current checkout behavior.
+- Open PRs are active branch intent, not landed behavior.
+- Closed unmerged PRs are weak or superseded evidence.
+- Merged PRs are useful history but still require current code verification.
+
+## Authoring Templates
+
+When writing `PROFILE.md`, `resources/commits.md`, `resources/prs.md`, or `resources/issues.md`, read [repo-templates.md](repo-templates.md) and use it as fill-in scaffolding. Remove placeholders from final files and delete sections that are genuinely unavailable.
+
+Apply these rules even before loading the templates:
+
+- Use fixed-field resource sections separated by `---`; do not use Markdown tables for PRs or issues.
+- Write search-grade `Description` fields that explain what the PR/issue covers, when future agents should open it, affected modules/files/behaviors, concrete search cues, and evidence strength.
+- Do not copy raw summaries or headings into descriptions; synthesize routing cues from raw facets and current project understanding.
+- Do not add persistent `indexes/*.json` files or `index:` frontmatter; search `resources/*.md` directly and open raw JSON only for build/debug evidence.