OmicsMem

OmicsMem 是一个面向单细胞组学分析的 Agent 化实验框架。它把传统的 Scanpy 流水线、LLM 决策、可验证的 memory.jsonl、可复用的 SKILL.md、以及可量化验证实验放在同一个闭环里。

一句话概括：

先让程序稳定地做单细胞分析，再让 Agent 在关键决策点参与判断，最后把“被验证过的经验”沉淀成 memory 和 skill，供下一轮分析复用。

这个项目能做什么

• 读取 .h5ad 单细胞数据并执行标准分析流程
• 在关键节点让 LLM 参与决策
  • QC 阈值
  • 归一化策略
  • HVG 数量
  • 聚类参数
  • cluster 注释
• 将本轮经过验证的经验写入 memory.jsonl
• 把多条 verified memory 凝练成可复用的 SKILL.md
• 在下一轮运行中按组织、平台、marker 相似度自动检索和加载 skill
• 记录 skill 的调用痕迹，支持回溯“这次判断用了哪个 skill”
• 自带一键验证脚本，比较：
  • baseline_no_skill
  • seed_skill_accumulation
  • rerun_with_seeded_skills

它不是什么

OmicsMem 不是“让 LLM 自己随便操作 Python 环境”的自由代理。

它更像一种混合式架构：

• 程序负责固定、可重复的数据分析流程
• LLM 负责关键判断与经验总结
• Tool 负责真正执行 Scanpy 计算
• Memory 和 Skill 负责把经验带到下一次运行

这也是它更适合做实验、审计和持续验证的原因。

核心功能

1. 单细胞分析流水线

项目当前围绕单细胞 RNA-seq .h5ad 数据运行，主要流程包括：

1. 读入数据并构建数据集上下文
2. 质控与过滤
3. 归一化
4. 高变基因选择
5. PCA / neighbors / Leiden 聚类
6. marker 提取
7. cluster 注释
8. 评估结果
9. 反思并写入 memory
10. 从 verified memory 蒸馏 skill

2. Episodic Memory

memory.jsonl 记录的是“单次案例中的被验证经验”。

它更像病例记录，而不是通用手册。里面会保存：

• 决策点是什么
• 当时看到了哪些 marker
• 模型做了什么判断
• 结果是否正确
• 如果调用了 skill，当时用了哪些 skill、为什么选它

3. Skill System

SKILL.md 不是原始案例记录，而是从 verified memory 中抽象出来的“可复用指导说明”。

它更像：

• 某类 cluster 注释 checklist
• 某类混淆场景的排错手册
• 某个参数选择的经验规则

Skill 支持：

• 新建
• 更新已有 skill
• 替换旧 skill
• 记录版本和来源 memory

4. 一键验证实验

项目自带一键脚本，用相同数据集执行：

1. 不带 skill 的 baseline
2. 生成第一轮 skill 的 seed run
3. 带 seed skill 重跑同案例

这样可以直接量化“skill 积累有没有帮助”。

安装

要求：

• Python >=3.12

安装：

python -m venv .venv
source .venv/bin/activate
pip install -e .[test]

Windows PowerShell：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[test]

配置 LLM

最简单是使用 .env：

OMICSMEM_LLM_PROVIDER=openai
OPENAI_API_KEY=your-api-key
OMICSMEM_MODEL=gpt-5.2

如果你用的是 OpenAI 兼容网关：

OMICSMEM_LLM_PROVIDER=newapi
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://your-host
OMICSMEM_MODEL=gpt-5.2

说明：

• 当前项目已经兼容 OpenAI-compatible endpoint
• 实验里默认会把模型钉在更稳定的 gpt-5.2
• 如果你的网关对某些模型名不稳定，OmicsMem 也做了 fallback 处理

快速开始

1. 跑 demo

omicsmem-demo \
  --dataset data/d3566d6a-a455-4a15-980f-45eb29114cab.h5ad \
  --max-cells 200

等价命令：

python examples/deerflow_agent_demo.py \
  --dataset data/d3566d6a-a455-4a15-980f-45eb29114cab.h5ad \
  --max-cells 200

默认输出在：

results/deerflow_demo/

常见产物：

• result.json
• memory.jsonl
• skills/**/SKILL.md

2. 用固定 memory / skill 库持续积累

如果你希望 skill 不散落在单次运行目录里，建议显式指定固定目录：

omicsmem-run \
  --dataset data/d3566d6a-a455-4a15-980f-45eb29114cab.h5ad \
  --max-cells 200 \
  --memory-file memory/memory.jsonl \
  --skill-dir memory/skills \
  --output-dir results/persistent_run

当前仓库里已经同步了一份可长期查看的 skill 库：

memory/skills/

Demo 展示

一次典型运行会产出三类核心文件：

result.json

保存：

• 数据集上下文
• 实验指标
• 运行轨迹
• 哪些 skill 被调用了

memory.jsonl

保存：

• 本轮被验证通过的案例经验
• 每条经验来自哪个决策点
• 当时使用了哪些 skill
• skill 选择理由

skills/**/SKILL.md

保存：

• skill 名称
• 适用上下文
• rule / playbook
• provenance
• version / status

项目是怎么实现的

运行主链路

主入口在 src/omicsmem/experiments/runner.py。

它会：

1. 读取 .h5ad
2. 生成 DatasetContext
3. 加载历史 memory
4. 加载 skill 库
5. 创建 OmicsMem agent
6. 调用 pipeline
7. 写入 memory
8. 蒸馏 skill
9. 输出 result.json

Agent 如何参与

src/omicsmem/agent/base.py 里的 BaseOmicsAgent 本质上是一个调度壳。

它不是直接自己做数值分析，而是把工作交给 pipeline。

Tool 如何执行

src/omicsmem/tools/registry.py 注册了可用 tool：

• qc_tool
• normalize_tool
• hvg_tool
• cluster_tool
• marker_tool
• evaluate_tool

这些 tool 最终调用的是 src/omicsmem/tools/scanpy_tools.py 里的确定性 Scanpy 函数。

Memory 如何生成

src/omicsmem/memory/reflector.py 会对每一步结果做 verifier 检查。

只有通过验证的经验才会写进 memory.jsonl。

Skill 如何生成和调用

• skill 生成逻辑在 src/omicsmem/skills/distiller.py
• skill 存储和检索在 src/omicsmem/skills/store.py
• pipeline 在注释前会先检索 skill，再决定是否加载完整 SKILL.md

这套逻辑现在支持：

• active skill 直接参与
• needs_review skill 可以参与，但会降权
• deprecated skill 不参与

可量化验证结果

下面这些结果都来自仓库里的真实一键实验，设置统一为：

• max_cells=200
• fixed preprocessing
• baseline / seed / rerun 三阶段对比

结果总表

Dataset	Tissue / Platform	Baseline Weighted	Rerun Weighted	Delta	Baseline Cluster	Rerun Cluster	Delta	Skills Loaded In Rerun	Skill Trace Count
d3566d6a-a455-4a15-980f-45eb29114cab.h5ad	bone marrow / BD Rhapsody Targeted mRNA	1.000	1.000	0.000	1.000	1.000	0.000	9	6
cd4c96bb-ad66-4e83-ba9e-a7df8790eb12.h5ad	bone marrow / BD Rhapsody Targeted mRNA	0.160	0.315	+0.155	0.200	0.400	+0.200	4	2
c05fb583-eb2f-4e3a-8e74-f9bd6414e418.h5ad	bone marrow / BD Rhapsody Whole Transcriptome Analysis	0.310	0.410	+0.100	0.333	0.500	+0.167	8	3

结果怎么解读

• 第 1 个数据集本来 baseline 就是满分，所以 skill 没有进一步提升空间
• 第 2 个数据集上，skill 把 weighted_accuracy 从 0.16 提升到 0.315
• 第 3 个数据集上，skill 把 weighted_accuracy 从 0.31 提升到 0.41

这说明：

• skill 现在已经不是“生成了但没被调用”
• 它已经能在别的数据集上产生可见的正向收益
• 同时它不是魔法，提升通常发生在 skill 库覆盖到的具体混淆场景上

对应实验报告：

• experiment/artifacts/small_skill_validation/validation_report.md
• experiment/artifacts/cd4c96bb_skill_validation/validation_report.md
• experiment/artifacts/c05fb583_skill_validation/validation_report.md

如何复现实验

默认小规模实验

./experiment/run_small_skill_validation.sh

指定别的数据集

例如运行 cd4c96bb...：

OMICSMEM_VALIDATION_DATASET=data/cd4c96bb-ad66-4e83-ba9e-a7df8790eb12.h5ad \
OMICSMEM_VALIDATION_ARTIFACT=cd4c96bb_skill_validation \
OMICSMEM_VALIDATION_FIXED_MIN_GENES=30 \
OMICSMEM_VALIDATION_FIXED_MAX_PCT_MT=25 \
OMICSMEM_VALIDATION_MAX_CELLS=200 \
./experiment/run_small_skill_validation.sh

例如运行 c05fb583...：

OMICSMEM_VALIDATION_DATASET=data/c05fb583-eb2f-4e3a-8e74-f9bd6414e418.h5ad \
OMICSMEM_VALIDATION_ARTIFACT=c05fb583_skill_validation \
OMICSMEM_VALIDATION_FIXED_MIN_GENES=200 \
OMICSMEM_VALIDATION_FIXED_MAX_PCT_MT=15 \
OMICSMEM_VALIDATION_MAX_CELLS=200 \
./experiment/run_small_skill_validation.sh

项目结构

src/omicsmem/
  agent/       Agent 外壳、prompt、LLM 调用
  core/        schema、config
  domain/      marker 规则、标签归一化
  tools/       Scanpy tool 封装和 registry
  memory/      反思、检索、工作记忆
  skills/      SKILL.md 的生成、加载、检索、更新
  pipeline/    主分析流水线
  experiments/ h5ad 运行入口与 CLI

examples/      demo
experiment/    一键实验脚本
memory/        推荐长期 skill / memory 库
results/       常规运行结果
docs/          设计说明与入门文档
tests/         测试

测试

pytest -q

推荐阅读

• 深入设计说明： docs/REFACTOR_REPORT.md
• 零基础流程说明： docs/PIPELINE_FOR_HUMANS.md