ai-memex-cli CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

ai-memex-cli（命令名 memex）是一个用于构建和维护持久化 LLM wiki 的 CLI 工具。它的核心定位是“机械层”：只做文件操作、frontmatter 校验、关键词匹配、链接检查等纯机械工作；所有语义决策（写什么内容、如何综合知识）都交给外部 LLM agent 通过 shell 调用来完成。

核心理念（区别于 RAG）：wiki 是 compounding artifact（累积产物），不是查询时即兴重组的检索结果。LLM 在 ingest 时把新源整合进现有 wiki（更新 entity/concept 页、修订 summary、标注矛盾），知识编译一次后持续保持现行；查询时不再从零拼接。Agent 拥有 wiki/ 层——人几乎不手写 wiki，LLM 写并维护交叉引用、矛盾标注、综合页；CLI 守住 raw/ 的不可变性与机械正确性。该模式源自 Karpathy 的 LLM Wiki pattern，精神承自 Vannevar Bush 的 Memex（1945）。

技术栈

• 运行时：Node.js >= 20
• 语言：TypeScript 5.4（严格模式 strict: true）
• 模块系统：ES Modules（"type": "module"），内置模块导入需带 node: 前缀
• CLI 框架：cac
• 测试框架：vitest（globals: true，environment: 'node'）
• 依赖库：gray-matter、chokidar、picocolors
• 包管理器：pnpm
• 构建工具：tsc 直接编译，输出到 dist/

编码规范

• 文件命名：命令文件使用 kebab-case（如 link-check.ts），模块文件使用 camelCase（如 wiki-index.ts）
• 导出约定：每个命令文件导出 *Command 异步函数（如 distillCommand）；核心模块导出具体函数而非默认导出
• 类型命名：接口/类型使用 PascalCase（如 DistillOptions、WikiPage）
• 导入顺序：Node 内置模块（带 node: 前缀）→ 第三方依赖 → 项目内部模块
• 路径风格：内部统一使用正斜杠（/），normalizePath() 处理 Windows 反斜杠
• 禁止项：禁止引入与现有设计重复的大型框架

项目结构

src/
  cli.ts              # CLI 入口，使用 cac 注册所有命令
  commands/           # 各命令实现（init、distill、ingest、watch、glob、inject、lint、search、new、log、install-hooks、status、link-check）
  core/               # 核心领域逻辑（无 side effect 的纯函数优先）
    vault.ts          # Vault 路径解析
    config.ts         # 配置读写（~/.llmwiki/config.json）
    schema.ts         # Frontmatter 解析与校验
    wiki-index.ts     # Wiki 页面索引构建、[[link]] 提取
    globber.ts        # 关键词评分与页面筛选
    linker.ts         # 孤儿页、断链检测
    distiller.ts      # JSONL 解析与机械提取
    injector.ts       # @include 指令解析
  utils/
    fs.ts             # 文件系统封装（readFileUtf8、writeFileUtf8、listMarkdownFiles 等）
    exec.ts           # 子进程调用封装
    logger.ts         # 终端日志（info / success / warn / error）
templates/            # AGENTS.md 与 wiki 页面模板（concept、entity、source、summary）
tests/
  core/               # 核心模块单元测试
  fixtures/
    mock-vault/       # 完整 mock vault 结构，供测试使用
docs/                 # PRD 与设计文档
dist/                 # tsc 编译输出（.gitignore 忽略）