aim-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

aim-init

Wire a repo into ai-memory so its sessions auto-capture and the agent recalls durable knowledge. Works greenfield or brownfield (incl. migrating off the old

qmd

wiki/

stack — see wiki-init for the legacy pattern).

ai-memory replaces the qmd
wiki/
+ local-index stack: knowledge lives server-side in the ai-memory instance (recalled via the MCP), not in a per-repo
wiki/
folder. Full usage model in references/usage.md.

将仓库接入ai-memory，使其会话可自动捕获，且Agent能调用持久化知识。适用于新项目（绿地项目）或已有项目（棕地项目），包括从旧

qmd

wiki/

栈迁移——遗留模式详见wiki-init。

ai-memory替代了qmd的
wiki/
+本地索引栈：知识存储在ai-memory实例的服务器端（通过MCP调用），而非每个仓库的
wiki/
文件夹。完整使用模式见references/usage.md。

Route intent

路由意图

"como está?", "preciso migrar?", "doctor" → run doctor (read-only diagnosis).
"configura ai-memory aqui", "liga a captura", "init" → install (greenfield).
"migra do qmd", "tira o qmd e põe ai-memory" → migrate (brownfield).

Before writing anything, confirm the three routing parameters with the user — there can be multiple ai-memory instances (e.g. a personal

memory.djalmajr.dev

, a separate org instance), so never hardcode the endpoint:

MCP endpoint — the ai-memory instance URL (e.g.
```
https://memory.djalmajr.dev/mcp
```
) and the server name to register it under (e.g.
```
memory-personal
```
,
```
memory-zomme
```
). Ask which instance this repo should talk to.
Workspace — personal →
```
default
```
; org repo → its own workspace (e.g.
```
zommehq
```
).
Project — defaults to the repo basename; let the user override.

The endpoint chosen here is what

aim-query

aim-write

will target later (by server name).

"como está?"、"preciso migrar?"、"doctor" → 运行doctor（只读诊断）。
"configura ai-memory aqui"、"liga a captura"、"init" → install（新项目初始化）。
"migra do qmd"、"tira o qmd e põe ai-memory" → migrate（已有项目迁移）。

在写入任何内容之前，需与用户确认三个路由参数——可能存在多个ai-memory实例（例如个人实例

memory.djalmajr.dev

、独立组织实例），因此切勿硬编码端点：

MCP端点——ai-memory实例的URL（例如
```
https://memory.djalmajr.dev/mcp
```
），以及注册时使用的服务器名称（例如
```
memory-personal
```
、
```
memory-zomme
```
）。询问该仓库应连接哪个实例。
工作区——个人项目→
```
default
```
；组织仓库→专属工作区（例如
```
zommehq
```
）。
项目——默认值为仓库的基础名称；允许用户自定义。

此处选择的端点将是后续

aim-query

aim-write

的目标（通过服务器名称）。

What a wired repo has

已接入仓库的组成

.ai-memory.toml
at the repo root — routes captures + recall to a workspace/project. Operator-local: it must be git-ignored (add
```
.ai-memory.toml
```
to the global gitignore,
```
git config --global core.excludesfile
```
, so it never lands in shared/public repos).
toml
```
workspace = "default"
project   = "<repo-name>"
```
Routing snippet in
```
CLAUDE.md
```
and
```
AGENTS.md
```
— the
```
…end -->
```
block (template: templates/routing-snippet.md). Drives proactive recall mid-session. The canonical block can also be fetched from the MCP via the
```
memory_install_self_routing
```
tool.
MCP server entry in
```
.mcp.json
```
(Claude),
```
opencode.json
```
(OpenCode),
```
.codex/config.toml
```
(Codex) — points at the ai-memory instance (template: templates/mcp-entry.json). This is operator-local routing (the endpoint is per-operator — your instance, your auth), so keep it out of git the same way as the marker: add .mcp.json
to the global gitignore. (
```
.mcp.json
```
is pure MCP config — safe to ignore wholesale.
```
opencode.json
```
/
```
.codex/config.toml
```
hold other settings too, so handle per your existing convention.) If the file is already tracked,
```
git rm --cached .mcp.json
```
to untrack it (keeps the file). Committing it forces collaborators onto your instance and leaks the endpoint in shared/public repos.
Auto-capture hooks are global (
```
~/.claude/settings.json
```
+
```
~/.config/ai-memory/hooks/
```
), marker-gated: they fire in any repo that has
```
.ai-memory.toml
```
. So a repo needs no per-repo hook scripts — just the marker. (Legacy qmd repos have per-repo
```
wiki-reindex
```
hooks; migration removes them.)

仓库根目录下的**
```
.ai-memory.toml
```
——将捕获和调用路由至指定工作区/项目。该文件为操作员本地文件：必须被git忽略**（将
```
.ai-memory.toml
```
添加到全局git忽略列表，即
```
git config --global core.excludesfile
```
，确保它不会进入共享/公开仓库）。
toml
```
workspace = "default"
project   = "<repo-name>"
```
```
CLAUDE.md
```
和
```
AGENTS.md
```
中的路由片段——
```
…end -->
```
代码块（模板见templates/routing-snippet.md）。用于在会话中主动触发知识调用。标准代码块也可通过
```
memory_install_self_routing
```
工具从MCP获取。
```
.mcp.json
```
（Claude）、
```
opencode.json
```
（OpenCode）、
```
.codex/config.toml
```
（Codex）中的MCP服务器条目——指向ai-memory实例（模板见templates/mcp-entry.json）。这是操作员本地路由（端点为操作员专属——你的实例，你的权限），因此需像处理标记文件一样避免提交到git：将**
```
.mcp.json
```
**添加到全局git忽略列表。（
```
.mcp.json
```
是纯MCP配置——可直接忽略。
```
opencode.json
```
/
```
.codex/config.toml
```
还包含其他设置，因此需按照现有约定处理。）如果该文件已被追踪，执行
```
git rm --cached .mcp.json
```
取消追踪（保留本地文件）。提交该文件会强制协作者使用你的实例，并在共享/公开仓库中泄露端点信息。
自动捕获钩子是全局的（
```
~/.claude/settings.json
```
+
```
~/.config/ai-memory/hooks/
```
），由标记文件触发：在任何包含
```
.ai-memory.toml
```
的仓库中都会生效。因此仓库无需专属钩子脚本——只需标记文件即可。（遗留qmd仓库有仓库专属的
```
wiki-reindex
```
钩子；迁移时需移除它们。）

doctor (read-only)

doctor（只读诊断）

Report, without writing:

Is there a
```
.ai-memory.toml
```
? What workspace/project? Is it git-ignored?
Is the routing snippet present in CLAUDE.md / AGENTS.md?
Is an ai-memory MCP entry present in
```
.mcp.json
```
/
```
opencode.json
```
/
```
.codex/config.toml
```
? Is
```
.mcp.json
```
git-ignored (operator-local) rather than tracked?
Legacy qmd? Flag any of: a
```
qmd
```
MCP entry, a
```
wiki/
```
dir with
```
CONVENTIONS.md
```
, per-repo
```
*/hooks/wiki-reindex.sh
```
, a "Wiki (
```
wiki/
```
)" block in CLAUDE.md/AGENTS.md,
```
.wiki-guardrails.yml
```
.

仅生成报告，不写入内容：

是否存在
```
.ai-memory.toml
```
？工作区/项目是什么？是否被git忽略？
CLAUDE.md/AGENTS.md中是否存在路由片段？
```
.mcp.json
```
/
```
opencode.json
```
/
```
.codex/config.toml
```
中是否存在ai-memory MCP条目？
```
.mcp.json
```
是否被git忽略（操作员本地文件）而非被追踪？
是否为遗留qmd仓库？ 检查以下任一特征：
```
qmd
```
MCP条目、包含
```
CONVENTIONS.md
```
的
```
wiki/
```
目录、仓库专属的
```
*/hooks/wiki-reindex.sh
```
、CLAUDE.md/AGENTS.md中的"Wiki (
```
wiki/
```
)"代码块、
```
.wiki-guardrails.yml
```
。

install (greenfield)

install（新项目初始化）

Confirm workspace + project with the user.
Ensure
```
.ai-memory.toml
```
is git-ignored globally (see step 1 above), then write the marker.
Insert the routing snippet into
```
CLAUDE.md
```
and
```
AGENTS.md
```
(idempotent — between the
```

```
/
```

```
markers; replace if already present).
Add the ai-memory MCP entry to the agent configs the repo uses, and ensure
```
.mcp.json
```
is git-ignored (operator-local — see item 3 above);
```
git rm --cached .mcp.json
```
if already tracked.
Tell the user auto-capture is now live (global hooks + the new marker); recall is via the session-start handoff + the routing snippet.

与用户确认工作区和项目信息。
确保
```
.ai-memory.toml
```
已被全局git忽略（见上文步骤1），然后写入标记文件。
将路由片段插入
```
CLAUDE.md
```
和
```
AGENTS.md
```
（幂等操作——插入到
```

```
/
```

```
标记之间；若已存在则替换）。
将ai-memory MCP条目添加到仓库使用的Agent配置中，并确保
```
.mcp.json
```
被git忽略（操作员本地文件——见上文第3点）；若已被追踪则执行
```
git rm --cached .mcp.json
```
。
告知用户自动捕获已启用（全局钩子+新标记文件）；知识调用可通过会话启动交接和路由片段实现。

migrate (brownfield: qmd → ai-memory)

migrate（已有项目迁移：qmd → ai-memory）

Run doctor first; then, with the user's confirmation:

Marker — write
```
.ai-memory.toml
```
(workspace/project), git-ignored.
MCP — in
```
.mcp.json
```
/
```
opencode.json
```
/
```
.codex/config.toml
```
, replace the
```
qmd
```
server entry with the ai-memory entry. Ensure
```
.mcp.json
```
is git-ignored (operator-local);
```
git rm --cached .mcp.json
```
if it was tracked.
CLAUDE.md / AGENTS.md — replace the "Wiki (
```
wiki/
```
)" / qmd-MCP block with the routing snippet. Drop instructions that tell the agent to query
```
qmd
```
or maintain
```
wiki/
```
.
Remove ALL qmd-era artifacts.
```
wiki-init
```
installs more than hooks — enumerate against wiki-init and remove every one:
- .wiki-guardrails.yml
  (guardrails config).
- Hooks —
```
.claude/hooks/wiki-*.sh
```
  (policy-check, reindex, drift-audit, suggest-ingest);
```
.codex/hooks/wiki-*.sh
```
  (policy-check, reindex, drift-audit, consider) +
  .codex/hooks.json
  ;
```
.opencode/hooks/wiki-*.sh
```
  +
  .opencode/plugins/wiki-guardrails.js
  . Remove the matching hook entries from
```
.claude/settings.json
```
  , and
```
[features] codex_hooks = true
```
  from
```
.codex/config.toml
```
  (it only existed to enable the codex wiki hooks).
- opencode.json
```
permission.skill."wiki-*"
```
  (swap to
```
"aim-*"
```
  or drop).
- ANTIGRAVITY (if the repo uses it) — the managed instruction block + any
```
.antigravity*
```
  hooks/config.
- Auto-capture now comes from the global ai-memory hooks — no per-repo hook scripts needed.
Global QMD checkout/wrapper (operator-level, outside the repo) — the per-project wrapper (
```
~/.local/share/skills/qmd/wrappers/<project>-qmd
```
, or the legacy
```
~/.local/share/essential-skills/qmd/...
```
) and the managed
```
qmd
```
checkout/cache are now orphaned. Remove the wrapper; remove the shared checkout only if no other repo still uses qmd.
wiki/
content — leave it in place as history by default. If the user wants it in ai-memory, ingest the markdown into the chosen workspace/project (one page per file, redact any literal secrets) and then they can remove
```
wiki/
```
. Do not delete
```
wiki/
```
without explicit confirmation.
Re-run doctor to confirm: marker present + git-ignored, snippet in CLAUDE/AGENTS, ai-memory MCP wired, and no qmd remnants (no
```
.wiki-guardrails.yml
```
, no
```
wiki-*
```
hooks/ plugins, no qmd MCP entry, no
```
codex_hooks
```
/
```
wiki-*
```
permission leftovers).

先运行doctor诊断；然后在用户确认后执行以下步骤：

标记文件——写入
```
.ai-memory.toml
```
（指定工作区/项目），并设置为git忽略。
MCP配置——在
```
.mcp.json
```
/
```
opencode.json
```
/
```
.codex/config.toml
```
中，替换
```
qmd
```
服务器条目为ai-memory条目。确保
```
.mcp.json
```
被git忽略（操作员本地文件）；若已被追踪则执行
```
git rm --cached .mcp.json
```
。
CLAUDE.md / AGENTS.md——将"Wiki (
```
wiki/
```
)" / qmd-MCP代码块替换为路由片段。删除所有指示Agent查询
```
qmd
```
或维护
```
wiki/
```
的说明。
移除所有qmd时代的产物。
```
wiki-init
```
安装的不止钩子——对照wiki-init列出所有内容并移除：
- .wiki-guardrails.yml
  （护栏配置）。
- 钩子——
```
.claude/hooks/wiki-*.sh
```
  （策略检查、重新索引、漂移审计、建议导入）；
```
.codex/hooks/wiki-*.sh
```
  （策略检查、重新索引、漂移审计、考量）+
  .codex/hooks.json
  ；
```
.opencode/hooks/wiki-*.sh
```
  +
  .opencode/plugins/wiki-guardrails.js
  。从
```
.claude/settings.json
```
  中移除对应的钩子条目，并从
```
.codex/config.toml
```
  中删除
```
[features] codex_hooks = true
```
  （该配置仅用于启用codex wiki钩子）。
- **
```
opencode.json
```
  **中的
```
permission.skill."wiki-*"
```
  （替换为
```
"aim-*"
```
  或删除）。
- ANTIGRAVITY（若仓库使用）——托管指令块 + 所有
```
.antigravity*
```
  钩子/配置。
- 自动捕获现在由全局ai-memory钩子实现——无需仓库专属钩子脚本。
全局QMD检出/包装器（操作员级别，仓库外部）——项目专属包装器（
```
~/.local/share/skills/qmd/wrappers/<project>-qmd
```
，或遗留的
```
~/.local/share/essential-skills/qmd/...
```
）以及托管的
```
qmd
```
检出/缓存现在已无用。移除包装器；仅当没有其他仓库仍使用qmd时，再移除共享检出内容。
wiki/
内容——默认保留作为历史记录。如果用户希望将其存入ai-memory，将markdown文件导入指定工作区/项目（每个文件对应一个页面，编辑掉任何明文机密），之后用户可自行删除
```
wiki/
```
。未经用户明确确认，请勿删除
wiki/
。
重新运行doctor确认：标记文件存在且被git忽略，路由片段已加入CLAUDE/AGENTS，ai-memory MCP已接入，且无qmd残留（无
```
.wiki-guardrails.yml
```
、无
```
wiki-*
```
钩子/插件、无qmd MCP条目、无
```
codex_hooks
```
/
```
wiki-*
```
权限残留）。

Verify

验证

```
git check-ignore .ai-memory.toml
```
→ ignored (not committed).
Routing snippet present once (between the markers) in CLAUDE.md + AGENTS.md.
No
```
qmd
```
MCP entry /
```
wiki-reindex
```
hooks remain (for migrate).
A capture round-trips: a real agent session in the repo lands a page under the chosen workspace/project (check via
```
aim-status
```
/
```
memory_status
```
or
```
/api/v1/projects
```
).

See references/usage.md for the recall model (handoff per project, auto-capture, the MCP tools) and aim-query / aim-write for manual recall/write.

执行
```
git check-ignore .ai-memory.toml
```
→ 显示已忽略（未提交）。
CLAUDE.md和AGENTS.md中各存在一段路由片段（位于标记之间）。
无
```
qmd
```
MCP条目 /
```
wiki-reindex
```
钩子残留（针对迁移场景）。
捕获功能正常：在该仓库中进行一次真实Agent会话后，对应工作区/项目下会生成一个页面（可通过
```
aim-status
```
/
```
memory_status
```
或
```
/api/v1/projects
```
检查）。

知识调用模型（按项目交接、自动捕获、MCP工具）详见references/usage.md，手动调用/写入功能详见aim-query / aim-write。",