架构概览

memex-server 是一个 Wiki 生成编排服务，核心职责是把书籍或文本语料组织成可恢复、可审计、可监督的 Agent 执行流水线，驱动引擎依次完成 egg → boot → grow → butler 四个阶段。

分层结构

用户 / 外部系统
  ├─ CLI: memex
  ├─ Web UI: FastAPI + Jinja2
  ├─ HTTP API: /api/v1/*
  └─ MCP: FastMCP
            │
            ▼
      接入层（Adapter）
  ├─ memex.cli
  ├─ memex.web
  ├─ memex.api.routes / sse / auth / scheduler
  └─ memex.mcp_server
            │
            ▼
      Core 编排层
  ├─ core.service          ← 多入口共享服务层
  ├─ core.task_manager     ← 任务状态数据中枢
  ├─ core.wiki_execution   ← 阶段完成语义（磁盘证据）
  ├─ core.phase_review     ← 阶段质量复核
  ├─ core.wiki_runtime     ← 预览/Butler 运行态管理
  └─ core.job_diagnostics  ← 任务诊断
            │
            ▼
      Agent / 执行层
  ├─ agent.egg
  ├─ cli_phase / cli_skill
  └─ api.sse / job_runner（子进程）
            │
            ▼
      外部引擎层（运行时加载，不 vendoring）
  ├─ MEMEX_ROOT/specs
  ├─ MEMEX_ROOT/skills
  ├─ MEMEX_ROOT/wiki/scripts
  └─ MEMEX_ROOT/genes
            │
            ▼
      数据面
  ├─ SQLite / PostgreSQL（jobs / token / event / runtime）
  ├─ wiki 工作目录（磁盘证据）
  └─ 日志目录

核心架构原则

• 单一编排核心：memex.core.service 为多入口共享服务层，四种接入方式都调它
• 接入层薄封装：HTTP / MCP / CLI 只适配协议，不重复实现业务编排
• 以磁盘证据为准：阶段完成不依赖 Agent 自述，依赖 wiki_execution 验收落盘产物
• 异步任务后台化：长任务由独立子进程执行，前端通过 SSE 获取实时事件
• 引擎外置：引擎规范、skills、wiki scripts 通过 MEMEX_ROOT 运行时挂载，不 vendoring 到本仓库

技术栈

层次	技术
语言	Python 3.12
HTTP 框架	FastAPI + Uvicorn
CLI	Typer
模板	Jinja2
MCP	FastMCP
异步	asyncio + subprocess
数据库	SQLite（默认）/ PostgreSQL（生产）
ORM/查询	SQLAlchemy Core
部署	Docker Compose + Traefik