架构全景：从三端 capture 到画像自学习#

一图全景#

flowchart TB
    subgraph capture[三端 capture]
        CC[Claude Code<br/>SessionEnd hook]
        CX1[Codex notify<br/>wrapper]
        CX2[Codex FS-watch<br/>rollout_summaries]
        OC1[OpenClaw native<br/>plugin]
        OC2[OpenClaw FS-watch<br/>sessions/*.jsonl]
    end

    capture --> CLI[memoryd capture<br/>统一 CLI 入口]
    CLI --> STORE[Markdown SoT<br/>+ SQLite index]

    STORE --> KG[Knowledge Graph<br/>entities + relations<br/>+ supersedes_chain]
    STORE --> SR[Search<br/>ripgrep × Milvus Lite<br/>RRF + 实体加权]
    STORE --> GOV[Governance<br/>DURA + decay<br/>+ digest + audit]

    KG --> PROF[Profile<br/>weekly identity<br/>+ trends + 月度报告]
    GOV --> PROF
    SR --> PROF

    PROF --> UI[CLI / TUI / Web / MCP]
    STORE --> UI
    KG --> UI
    SR --> UI

    UI --> SYNC[Sync<br/>路径 A markdown 增量<br/>路径 B memories.json]
    SYNC --> CLOUD[(用户自配云盘)]

模块边界#

memoryd/src/memoryd/ —— 核心后端#

plugins/ —— 三端胶水#

写入路径#

sequenceDiagram
    actor U as 用户
    participant CC as Claude Code
    participant Hook as session-end.sh
    participant MD as memoryd capture
    participant FS as ~/.local/share/memoryd/
    participant SQL as SQLite index
    participant KG as knowledge_graph
    participant LLM as LLM provider

    U->>CC: 一轮对话结束
    CC->>Hook: SessionEnd hook 触发 (jsonl 路径)
    Hook->>MD: stdin = {session_id, transcript_path, cwd}
    MD->>MD: 解析 transcript，抽最后 50 轮
    MD->>FS: 写 sessions/<id>.md (frontmatter + body)
    MD->>SQL: INSERT memories + triggers
    MD-->>MD: fork subprocess: memoryd analyze-session <slug>
    Note over MD,LLM: 后台异步
    MD->>LLM: DURA 评分 + entity 抽取
    LLM-->>MD: dura_score + entities + relations
    MD->>SQL: UPDATE memories, INSERT entities, INSERT relations
    MD->>SQL: INSERT INTO promotions (status=pending) 如果 DURA ≥ 0.6
    MD->>KG: detect_supersedes_for_new_memory
    KG->>LLM: judge_supersedes 候选 prompt
    LLM-->>KG: SupersedeJudgment + 置信度
    KG->>SQL: INSERT INTO supersedes_chain

Codex / OpenClaw 走同一条 CLI 入口，仅 --source 不同：

• --source=claude-code —— CC SessionEnd hook
• --source=codex —— Codex notify wrapper（实时）
• --source=codex-rollout —— FS-watch rollout_summaries（事后兜底）
• --source=openclaw —— OpenClaw native plugin agent_end hook
• --source=openclaw-fs —— FS-watch openclaw sessions（兜底）
• --source=manual —— 手动 capture / mem_save 工具
• --source=importer-* —— 一次性 import

读取路径#

flowchart LR
    Q[query string] --> RG[ripgrep 关键词]
    Q --> VS[Milvus Lite 向量]
    RG --> RRF[RRF 重排]
    VS --> RRF
    KG[entity_ids] -.-> SC[实体加权]
    RRF --> SC
    SC --> RES[SearchResult top_k]
    RES --> CB[召回回填:<br/>recall_count++,<br/>last_recalled_at,<br/>decay_state→alive]

详见 搜索。

学习路径#

flowchart LR
    subgraph realtime[实时 - 每次 capture]
        E[抽 entities + relations]
        S[supersedes 检测]
    end
    subgraph weekly[每周 cron]
        I[LLM 重写 identity.md]
    end
    subgraph monthly[每月 cron]
        R[生成画像变化报告]
    end
    subgraph daily[每日 digest]
        T[trends 栏：top trigger + entity 上升]
    end

    realtime --> SQL[(SQLite)]
    SQL --> weekly
    weekly --> SQL
    weekly --> monthly
    SQL --> daily

详见 画像自学习。

同步路径#

flowchart LR
    A[Device A<br/>memoryd] -->|export| B1[路径 A:<br/>~/.local/share/memoryd/<br/>→ Dropbox 镜像]
    A -->|export| B2[路径 B:<br/>memories.json 单文件]
    B1 --> Cloud[(用户自配云盘)]
    B2 --> Cloud
    Cloud -->|import| C[Device B<br/>memoryd]

详见 跨设备同步。

UI 层（4 种）#

配置链#

环境变量
   ↓ 覆盖
~/.config/memoryd/config.toml
   ↓ 覆盖
默认值（memoryd/config.py 里 hardcoded）

字段总表见 架构 · 治理 配置章节。

设计原则总结#

• Markdown 是 source of truth，SQLite 可随时 rebuild-index 重建
• 本地优先，外网调用仅限可选 LLM provider；ONNX bge-m3 embedding 完全本地
• 三端等价，CC / Codex / OpenClaw 走同一后端，scope_hash 一致
• 可降级，LLM 不可用时 KG 走 jieba 兜底，embedding 不可用时只做关键词，所有失败都不阻塞 capture
• 可审计，所有写操作进 audit chain（SHA256 prev_hash 链）
• 不接管原生记忆，叠加层而非替换层