目录与数据布局

仓库目录结构

memex-server/
├── src/memex/
│   ├── api/          # HTTP 接入层（routes / sse / auth / scheduler）
│   ├── web/          # Web GUI（Jinja2 模板）
│   ├── core/         # Core 编排层（service / task_manager / wiki_execution …）
│   ├── agent/        # Agent 执行层
│   ├── harness_genes/
│   ├── harness_skills/
│   ├── cli.py        # CLI 主入口
│   └── mcp_server.py # MCP 主入口
├── tests/
├── docs/             # 原始技术文档
├── docker-compose.yml          # 生产（Traefik + TLS）
├── docker-compose.local.yml    # 本地开发
├── docker-compose.rollout.yml  # Web/Worker 独立 generation 发布覆盖
├── scripts/deploy.sh           # 生产滚动发布入口
├── Dockerfile
└── pyproject.toml

Wiki 数据根目录

以 MEMEX_WIKIS_DIR 为根：

MEMEX_WIKIS_DIR/
├── .uploads/              # 上传文件暂存
├── logs/server/           # 服务日志
└── <owner>/
    └── <slug>/
        ├── EGG.md         # egg 阶段蓝图
        ├── BIRTH.md       # boot 阶段种子层
        ├── GROW.md        # grow 阶段进展记录
        ├── corpus/        # 原始语料
        ├── docs/wiki/     # 生成的 wiki 页面
        │   ├── pages.json
        │   └── backlinks.json
        └── local/
            ├── memory/
            │   ├── boot_summary.md
            │   └── grow_baseline.md
            └── state/
                ├── lifecycle/          # EGG/BRH/GRW step checkpoint
                ├── grow_state.json
                ├── *.pid              # 进程 PID 文件
                └── serve.wanted       # 预览服务期望状态标记

关键业务流：上传到 Job 创建

POST /api/v1/upload  (或 upload-url / MCP / CLI)
  │
  ├─ 文件落地 .uploads/
  ├─ core.service.submit_book()
  │   ├─ 生成/校验 slug
  │   ├─ 内容指纹去重检查 → 命中则克隆已有成果（秒级返回）
  │   ├─ 未命中 → scaffold_wiki() 初始化 wiki 目录
  │   └─ TaskManager.create_job() → status=queued
  └─ 返回 {job_id, wiki_slug, target_dir}

关键业务流：Job 调度与执行

memex-background 启动
  ├─ generation heartbeat / active admission 检查
  ├─ scheduler_loop()（仅 active Worker 快速派发）
  │    ├─ 扫描 waiting 队列
  │    ├─ 检查：当前全局上限 / 单用户配额 / step 模型路由 quota
  │    └─ launch_job_runner()
  │         └─ 独立子进程：python -m memex.api.job_runner
  │              └─ /life <STEP_ID> --auto → checkpoint → 新 session
  └─ reconciler_loop()（低频对账）
       └─ orphan / timeout / config drift / 完成性恢复

生产中的 memex-background 运行在独立的 memex-worker-<release> project。新 generation 激活后，旧 generation 停止领取新任务，但已有 runner 会继续到持久 checkpoint 边界；这使 Web 的路由切换和 Worker 长任务收口成为两个互不阻塞的发布生命周期。

运行时关键文件

文件	作用
local/state/*.pid	进程 PID，用于进程存活检测
local/state/serve.wanted	预览服务期望状态，patrol 循环据此自愈
local/memory/boot_summary.md	boot 阶段验收依据
local/memory/grow_baseline.md	grow 阶段基线
local/state/grow_state.json	grow 进度状态，支持中断恢复
lifecycle step checkpoint	EGG/BRH/GRW 的 durable done/skipped/loop_active 状态
logs/butler/actions.jsonl	butler 行为结构化日志