memex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Memex — Idempotent Agent Memory Infrastructure

Memex — 幂等性Agent内存基础设施

Set up or audit the memex in the current repo. Safe to run multiple times — it checks what exists, reports what's missing or wrong, asks before making changes, then validates the result.

Announce at start: "Auditing memex..."

在当前代码仓库中设置或审核memex。可安全多次运行——它会检查已存在的内容，报告缺失或异常项，在进行更改前询问用户，然后验证结果。

启动时提示： "正在审核memex..."

Mode of Operation

运行模式

This skill is audit-first, then autonomous. Audit, report, and proceed to scaffold or repair without further prompting. The one exception is destructive operations (renaming or deleting existing files) — surface those before acting.

Audit — scan the repo and build a checklist of what exists vs what's expected.
Report — show the checklist to the user with status per item.
Fix — if issues are found, scaffold or repair them directly. Confirm only before destructive ops (e.g., renaming a spec folder).
Validate — after any creation or fix (and at the end of an audit-only run), run Phase 5 validation.

If the audit finds nothing wrong and validation passes, just say "Memex is healthy." and stop.

该技能遵循先审核，后自主执行的原则。先完成审核、报告，再直接进行搭建或修复，无需进一步提示。唯一例外是破坏性操作（重命名或删除现有文件）——执行前需向用户说明。

审核 —— 扫描仓库，对比预期内容与实际存在内容，生成检查清单。
报告 —— 向用户展示检查清单，标注每项的状态。
修复 —— 若发现问题，直接进行搭建或修复。仅在执行破坏性操作（如重命名规范文件夹）前需确认。
验证 —— 完成任何创建或修复操作后（以及仅审核模式运行结束时），执行第5阶段的验证步骤。

若审核未发现任何问题且验证通过，只需回复"Memex状态正常。"即可结束。

Phase 1 — Audit

第1阶段 —— 审核

Read

references/audit-checklist.md

for the full inventory of files and directories to check, the meaning of each status (

OK

MISSING

DRIFT

), drift criteria for

AGENTS.md

and

vault/constitution.md

, the report format, and special handling for date-prefixed spec folders.

Apply each check, then assemble the report described in that reference.

阅读

references/audit-checklist.md

获取需检查的文件和目录完整清单、各状态（

OK

MISSING

DRIFT

）的含义、

AGENTS.md

和

vault/constitution.md

的异常判定标准、报告格式，以及带日期前缀的规范文件夹的特殊处理规则。

执行每项检查，然后按照该参考文档中的说明生成报告。

Phase 2 — Report

第2阶段 —— 报告

Render the audit table per the format in

references/audit-checklist.md

. Summarize:

undefined

按照

references/audit-checklist.md

中的格式生成审核表格。并添加总结：

undefined

Summary

总结

X/Y items OK
N missing, M drifted


If anything is missing or drifted, proceed to Phase 3. If everything was `OK`, skip to Phase 5 (validation).

X/Y项状态正常
N项缺失，M项异常


若存在缺失或异常项，进入第3阶段。若所有项均为`OK`，直接跳至第5阶段（验证）。

Phase 3 — Prerequisites (first-time or fix)

第3阶段 —— 前置条件（首次设置或修复时）

Before creating files, gather project context:

Read
```
package.json
```
,
```
README.md
```
, or any existing docs to understand what the project is.
Detect the package manager (
```
pnpm-workspace.yaml
```
→ pnpm,
```
yarn.lock
```
→ yarn,
```
bun.lockb
```
→ bun, else npm).
Detect the tech stack (frameworks, languages, deploy targets) from dependencies and config files.

This information is required to fill

AGENTS.md

and

vault/constitution.md

without surviving placeholders.

在创建文件前，收集项目上下文信息：

读取
```
package.json
```
、
```
README.md
```
或任何现有文档，了解项目定位。
检测包管理器（存在
```
pnpm-workspace.yaml
```
则为pnpm，
```
yarn.lock
```
则为yarn，
```
bun.lockb
```
则为bun，否则为npm）。
从依赖项和配置文件中检测技术栈（框架、语言、部署目标）。

这些信息用于填充

AGENTS.md

和

vault/constitution.md

，避免留下占位符。

Phase 4 — Scaffold (only the items that need it)

第4阶段 —— 搭建（仅处理需修复的项）

Create or repair only the items the audit flagged. Never touch files that are already

OK

仅创建或修复审核中标记的问题项。绝不改动状态为

OK

的文件。

Vault files

Vault文件

For

.obsidian/*.json

, atomic note templates (

templates/learning.md

rule.md

convention.md

), spec templates (

_template/spec.md

plan.md

tasks.md

), and the five MOCs in

_index/

, read

references/vault-files.md

and write each file from the spec there. Use the project name from Prerequisites to substitute

{{Project Name}}

in MOCs.

对于

.obsidian/*.json

、原子笔记模板（

templates/learning.md

、

rule.md

、

convention.md

）、规范模板（

_template/spec.md

、

plan.md

、

tasks.md

）以及

_index/

中的5个MOC，读取

references/vault-files.md

并按照其中的规范编写每个文件。使用前置条件中获取的项目名称替换MOC中的

{{Project Name}}

。

Constitution

章程文件

For

vault/constitution.md

, read

references/constitution-template.md

. It contains the template and filling rules — this is the most important file in the vault and must not be left with

{{placeholders}}

. If you don't have enough info to fill a section, ask the user; never commit unsubstituted placeholders.

对于

vault/constitution.md

，读取

references/constitution-template.md

。该文件包含模板及填充规则——这是vault中最重要的文件，绝不能留下

{{placeholders}}

占位符。若信息不足无法填充某部分，需询问用户；绝不提交未替换占位符的文件。

AGENTS.md

For

AGENTS.md

at the repo root, read

references/agents-md-template.md

. Fill

{{Project Name}}

, the project description paragraph, and the

## Commands (most used)

section from Prerequisites. The reference lists all required section headers — none may be missing.

对于仓库根目录下的

AGENTS.md

，读取

references/agents-md-template.md

。使用前置条件中的信息填充

{{Project Name}}

、项目描述段落以及

## Commands (most used)

部分。参考文档中列出了所有必填的章节标题——不得缺失任何一项。

CLAUDE.md symlink (Claude Code back-compat)

CLAUDE.md 符号链接（兼容Claude Code）

AGENTS.md

is the universal agent entry point. Claude Code historically reads

CLAUDE.md

instead, so a symlink at the repo root keeps it satisfied without duplicating content. Other agents ignore the file.

CLAUDE.md

does not exist at the repo root:

bash

ln -s AGENTS.md CLAUDE.md

AGENTS.md

是通用的Agent入口文件。Claude Code历史上读取的是

CLAUDE.md

，因此在仓库根目录创建符号链接可满足其需求，无需重复内容。其他Agent会忽略该文件。

若仓库根目录不存在

CLAUDE.md

：

bash

ln -s AGENTS.md CLAUDE.md

.gitignore additions

.gitignore 追加内容

Append these lines to the repo's

.gitignore

(skip if already present):

undefined

向仓库的

.gitignore

中追加以下内容（若已存在则跳过）：

undefined

Obsidian vault config (machine-local — Obsidian rewrites these on every open)

Obsidian vault配置（本地机器专属——Obsidian每次打开都会重写这些文件）

vault/.obsidian/


Rationale: Obsidian rewrites `app.json`, `appearance.json`, `core-plugins.json`, and the workspace files every time the vault is opened, which creates constant `git status` noise. The memex installer still **creates** the three config JSONs locally during scaffolding (so `useMarkdownLinks: false` / `newLinkFormat: "relative"` are set the first time Obsidian opens — wikilinks in the MOCs depend on this), but they are not tracked. Obsidian preserves existing user settings when it rewrites these files, so the defaults persist locally on subsequent opens.

vault/.obsidian/


理由：Obsidian每次打开vault都会重写`app.json`、`appearance.json`、`core-plugins.json`及工作区文件，这会导致`git status`持续出现冗余信息。memex安装程序在搭建过程中仍会**本地创建**这三个配置JSON文件（以便Obsidian首次打开时设置`useMarkdownLinks: false` / `newLinkFormat: "relative"`——MOC中的维基链接依赖此设置），但不会追踪这些文件。Obsidian重写这些文件时会保留用户现有设置，因此默认设置会在后续打开时持续生效。

Skills and commands (copy from scaffold/)

技能与命令（从scaffold/复制）

All bundled skills and commands live in

scaffold/

alongside this

SKILL.md

Skills are agent-agnostic and install canonically under

.agents/skills/<name>/

(the open agent skills standard's location, also discoverable by

npx skills

and similar tooling). For each agent-specific discovery directory already present in the repo (

.claude/

.codex/

.cursor/

.opencode/

.aider/

.augment/

, etc.), the memex installer adds a per-skill symlink so that agent picks up the skill without duplicating files on disk:

bash

MEMEX_DIR="<directory where this SKILL.md lives>"
SKILL_NAMES=(memex-recall memex-brainstorming memex-writing-plans memex-link)

所有捆绑的技能和命令都与本

SKILL.md

一同存放在

scaffold/

目录下。

技能与Agent无关，标准安装路径为

.agents/skills/<name>/

（开放Agent技能标准指定的路径，也可通过

npx skills

等工具发现）。对于仓库中已存在的每个Agent专属发现目录（

.claude/

、

.codex/

、

.cursor/

、

.opencode/

、

.aider/

、

.augment/

等），memex安装程序会为每个技能添加符号链接，使对应的Agent无需在磁盘上复制文件即可获取该技能：

bash

MEMEX_DIR="<本SKILL.md所在目录>"
SKILL_NAMES=(memex-recall memex-brainstorming memex-writing-plans memex-link)

1. Canonical install — single source of truth on disk

1. 标准安装——磁盘上的单一可信源

mkdir -p .agents/skills for name in "${SKILL_NAMES[@]}"; do [ -e ".agents/skills/$name" ] && continue # idempotent: don't overwrite cp -r "$MEMEX_DIR/scaffold/skills/$name" ".agents/skills/$name" done

mkdir -p .agents/skills for name in "${SKILL_NAMES[@]}"; do [ -e ".agents/skills/$name" ] && continue # 幂等性：不覆盖已存在内容 cp -r "$MEMEX_DIR/scaffold/skills/$name" ".agents/skills/$name" done

Ensure scripts are executable (only one skill ships scripts today)

确保脚本可执行（目前仅有一个技能包含脚本）

[ -d .agents/skills/memex-brainstorming/scripts ] &&
chmod +x .agents/skills/memex-brainstorming/scripts/*.sh

2. Per-agent symlinks — only into discovery dirs that already exist

2. 按Agent添加符号链接——仅针对已存在的发现目录

(do NOT auto-create agent dirs; their absence means the user does

（请勿自动创建Agent目录；目录不存在意味着用户未在此仓库中使用该Agent）。

not run that agent in this repo).

—

for agent_dir in .claude .codex .cursor .opencode .aider .augment; do [ -d "$agent_dir" ] || continue mkdir -p "$agent_dir/skills" for name in "${SKILL_NAMES[@]}"; do target="$agent_dir/skills/$name" [ -e "$target" ] && continue # idempotent: keep whatever's there ln -s "../../.agents/skills/$name" "$target" done done


**Slash commands** are a Claude Code-specific concept (no other current agent has an equivalent), so they install only into `.claude/commands/`. If `.claude/` does not exist in the repo, skip the command copy entirely — the workflows the commands encode are useful in any agent, but the user invokes them via prose prompts on those agents, not via `/foo` syntax.

```bash
if [ -d .claude ]; then
  mkdir -p .claude/commands
  for cmd in memex-open-pr memex-learn memex-spec memex-review-spec memex-sweep; do
    target=".claude/commands/$cmd.md"
    [ -e "$target" ] && continue
    cp "$MEMEX_DIR/scaffold/commands/$cmd.md" "$target"
  done
fi

Rules:

Skills always go to
```
.agents/skills/<name>
```
first (canonical), then symlinked into existing agent dirs.
Existing files are never overwritten — re-runs are no-ops on already-installed items.
Per-agent dirs that do not already exist are not auto-created by the skill copy; only an existing dir signals that agent is in use here.

for agent_dir in .claude .codex .cursor .opencode .aider .augment; do [ -d "$agent_dir" ] || continue mkdir -p "$agent_dir/skills" for name in "${SKILL_NAMES[@]}"; do target="$agent_dir/skills/$name" [ -e "$target" ] && continue # 幂等性：保留现有内容 ln -s "../../.agents/skills/$name" "$target" done done


**斜杠命令**是Claude Code专属概念（目前其他Agent无类似功能），因此仅安装到`.claude/commands/`目录。若仓库中不存在`.claude/`，则完全跳过命令复制——命令所包含的工作流对任何Agent都有用，但用户需通过自然语言提示在其他Agent上调用，而非`/foo`语法。

```bash
if [ -d .claude ]; then
  mkdir -p .claude/commands
  for cmd in memex-open-pr memex-learn memex-spec memex-review-spec memex-sweep; do
    target=".claude/commands/$cmd.md"
    [ -e "$target" ] && continue
    cp "$MEMEX_DIR/scaffold/commands/$cmd.md" "$target"
  done
fi

规则：

技能始终先安装到
```
.agents/skills/<name>
```
（标准路径），再符号链接到已存在的Agent目录。
绝不覆盖现有文件——重复运行时，已安装的项不会被改动。
技能复制时不会自动创建不存在的Agent目录；仅当目录已存在时，才表明用户在此仓库中使用该Agent。

Spec folder migration (if drift was reported)

规范文件夹迁移（若报告异常）

If the audit flagged any spec folder without a

YYYY-MM-DD-

prefix, migrate per the rules in

references/audit-checklist.md

(pull date from the spec file's frontmatter

created:

field, ask user when absent, never rename without confirmation).

若审核发现任何不带

YYYY-MM-DD-

前缀的规范文件夹，需按照

references/audit-checklist.md

中的规则进行迁移（从规范文件的前置元数据

created:

字段提取日期，若缺失则询问用户，绝不未经确认就重命名）。

Spec file rename migration (if drift was reported)

规范文件重命名迁移（若报告异常）

If the audit detected a spec folder containing generic

spec.md

plan.md

tasks.md

files (instead of the

<type>-<slug>.md

convention), migrate the folder. Renaming tracked files is a destructive operation — surface each detected folder, get explicit user confirmation per folder, then run the recipe below.

For each confirmed

<spec_dir>

(e.g.

vault/specs/2026-04-30-opensource-readiness/

bash

spec_dir="<the folder, e.g. vault/specs/2026-04-30-opensource-readiness>"
slug=$(basename "$spec_dir" | sed 's/^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-//')

若审核发现规范文件夹中包含通用的

spec.md

plan.md

tasks.md

文件（而非

<type>-<slug>.md

命名规范），需迁移该文件夹。重命名已追踪的文件属于破坏性操作——需向用户展示每个检测到的文件夹，获取用户针对每个文件夹的明确确认，再执行以下步骤。

针对每个已确认的

<spec_dir>

（例如

vault/specs/2026-04-30-opensource-readiness/

）：

bash

spec_dir="<目标文件夹，例如vault/specs/2026-04-30-opensource-readiness>"
slug=$(basename "$spec_dir" | sed 's/^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-//')

1. Rename each generic file to include the slug, preserving git history

1. 重命名每个通用文件以包含slug，保留git历史

for type in spec plan tasks; do src="$spec_dir/${type}.md" dst="$spec_dir/${type}-${slug}.md" [ -f "$src" ] && [ ! -e "$dst" ] && git mv "$src" "$dst" done

2. Update internal wikilinks inside every file in the folder

2. 更新文件夹内所有文件中的内部维基链接

[[spec]] / [[plan]] / [[tasks]] → [[<type>-<slug>]]

for f in "$spec_dir"/*.md; do sed -i.bak
-e "s/\[\[spec\]\]/[[spec-${slug}]]/g"
-e "s/\[\[plan\]\]/[[plan-${slug}]]/g"
-e "s/\[\[tasks\]\]/[[tasks-${slug}]]/g"
"$f" && rm "$f.bak" done

3. Update the specs MOC entry that pointed at the old basename

3. 更新指向旧文件名的规范MOC条目

folder=$(basename "$spec_dir") sed -i.bak
-e "s|/${folder}/spec$[|\]]$|/${folder}/spec-${slug}\1|g"
-e "s|/${folder}/plan$[|\]]$|/${folder}/plan-${slug}\1|g"
-e "s|/${folder}/tasks$[|\]]$|/${folder}/tasks-${slug}\1|g"
vault/_index/specs.md && rm vault/_index/specs.md.bak


After the recipe runs, also `grep -rln "\[\[spec\]\]\|\[\[plan\]\]\|\[\[tasks\]\]" vault/learnings/ vault/conventions/ vault/rules/` to surface any external wikilinks that might have pointed at the old basenames; update those manually with the user's confirmation (those references are not always intra-spec — they could legitimately mean "the spec template").

Note for the `sed` `-e` line: `[|\\]]` is a character class matching `|` or `]` — this scopes the replacement to wikilink edges so we do not match `<folder>/spec-tweaks.md` or other longer paths that happen to start with `spec`.


执行完上述步骤后，还需执行`grep -rln "\[\[spec\]\]\|\[\[plan\]\]\|\[\[tasks\]\]" vault/learnings/ vault/conventions/ vault/rules/`，找出可能指向旧文件名的外部维基链接；在用户确认后手动更新这些链接（这些引用不一定是规范内部的——它们可能确实指向"规范模板"）。

关于`sed` `-e`行的说明：`[|\\]]`是匹配`|`或`]`的字符类——这会将替换范围限定在维基链接的边缘，避免匹配到`<folder>/spec-tweaks.md`或其他以`spec`开头的长路径。

Phase 5 — Validate

第5阶段 —— 验证

After any creation or fix run, and at the end of an audit-only run with all

OK

, execute the validation checklist.

Read

references/validation.md

and run all 15 checks. Report results as the table specified there. If any check fails, surface the specific reason and ask "Want me to fix the failed checks?" Loop until clean or the user stops.

Validation is non-negotiable — this is what catches

{{placeholders}}

that survived scaffolding, missing AGENTS.md sections, broken symlinks, malformed JSON, and spec folders that slipped past the rename step.

在任何创建或修复操作完成后，以及所有项均为

OK

的仅审核模式运行结束时，执行验证检查清单。

阅读

references/validation.md

并执行全部15项检查。按照其中指定的表格格式报告结果。若任何检查失败，需说明具体原因并询问"需要我修复这些失败项吗？"，循环执行直至全部通过或用户停止。

验证是必不可少的步骤——这能捕捉到搭建过程中遗漏的

{{placeholders}}

占位符、缺失的AGENTS.md章节、损坏的符号链接、格式错误的JSON以及未通过重命名步骤的规范文件夹。

Final summary (always show at the end)

最终总结（始终在结尾展示）

undefined

undefined

Memex Audit Complete

Memex审核完成

X/Y items OK
N created, M fixed, K skipped (already correct)
Validation: 15/15 PASS (or list the FAILs)

{{only if first-time setup:}} Next steps:

Review vault/constitution.md — make sure it captures your non-negotiables
Run the project and start adding learnings to vault/learnings/
First feature? Copy vault/specs/_template/ and start a spec

undefined

X/Y项状态正常
创建N项，修复M项，跳过K项（已正确）
验证结果：15/15 通过（或列出失败项）

{{仅首次设置时显示：}} 后续步骤：

查看vault/constitution.md —— 确保它涵盖了你的核心规则
运行项目并开始向vault/learnings/添加学习记录
首个功能？复制vault/specs/_template/并开始编写规范

undefined