Concepts / Architecture

核心 runtime 和基础设施分层维护。

localmelo 的核心约束是：melo/ 负责 agent runtime 与 contracts， support/ 负责 config、backend、provider、onboarding 和 gateway。 Track 2 进一步把在线 working context 和 Hippo 的 durable memory routing 拆开，让 agent loop、memory、checker、executor 可以独立于具体模型服务演进。

整体架构图

这张图展示 online path 从用户入口到最终回答的主要流向，也标出 checker 边界、provider/backend seam，以及后续 sleep pipeline 的离线路径。 Memory 节点采用 Track 2 语义：working 负责 active session context， Hippo 负责 durable/specialized routing。

读图方式：实线表示 runtime 数据流，虚线表示 model/provider 或离线路径，橙色虚线区域表示 checker validation boundary。

melo - core agent runtime

support - infrastructure

checker - validation boundary validates: ingress · plan · execute · memory

用户 / Client

CLI or HTTP

infra

Gateway

sessions · HTTP

planner model consumer

Agent / Planner

main loop · orchestration

store model consumer

Memory

working + Hippo branches
history stays raw

executor

Executor

tools · builtins · policy

offline

Sleep

future personalization

planned offline workflow
preprocessing / training /
evaluation / promotion

infra model layer

Providers

LLM · Embedding contracts

infra

Backends

local · cloud · registry

infra

Config / Onboard

TOML config · probes

runtime 数据流

model / provider 路径

checker 边界

失败后重新规划

Track 2 / Memory Session

Memory 子图

当 agent 判断 candidate 值得记忆时，v1 中 agent-side decision 保持为 bool；同一份 candidate 并行发送给 working 和 Hippo。前者维护 active context，后者决定 durable 或 specialized placement。 long-term writes 需要等待相关 working memory 进入 rehearsed 状态，或出现其他 strong write signal。

online session

agent Remembered candidate bool=true proposal，不是 storage decision

working Working memory 短期 active cache；LRU-style refresh；只有 rehearsed memory 才能成为 long-term candidate

hippo Hippo router 选择 NEW、UPDATE、RELATED、CONFLICT 或 IGNORE；long-term writes 等待 rehearsal

promotion gate: fresh -> rehearsed 后才能 long-term persistence

durable and specialized memory

Long / Profile v1 使用一个 physical long store；用 semantic、episodic、profile、reflection metadata kinds 区分

Tools authoritative registry 加 procedural skill/template memory；不绕过 checker

Personalized Track 4 使用的 filtered sleep samples，不接收 raw history dump

History append-only task / step records，只用于 debugging、audit、replay 和 provenance

Working branch

重复使用的 active memory 会被 touch 或 compact，让当前任务上下文保持 bounded 且更新；只有 rehearsed memory 才能成为 long-term candidate。

Hippo branch

Hippo 负责 classification、metadata、provenance、relation links、conflict handling，以及立即写入还是 defer 到 sleep。

Extensible shape

同样的 subgraph 结构可以继续扩展到 agent、executor 和 sleep 细图，而不把这些 concern 塞进 memory session view。

需要保持的边界

边界	规则	原因
`melo/` 和 `support/`	`melo/` 不直接 import infrastructure implementation。	核心 runtime 保持可移植、可测试。
Agent 到 Executor	Tool call 先经过 checker 和 workspace policy。	危险 shell / file 操作在执行前被拒绝。
Agent 到 Memory	Agent 只提出 remembered candidate；经过 checker 限制后，working memory 和 Hippo 并行接收。	Agent 不依赖 SQLite、vector search、profile tables、tool memory internals 或 sleep samples。
History 到 PersonalizedMemory	`PersonalizedMemory` 只接收 selected sleep samples；不应直接 ingest raw history。	Track 4 得到 curated training inputs，不把 audit log 默认变成在线召回或训练数据。
Backend	本地 backend 只做 connector。	模型 runtime 的启动和管理不属于 localmelo core。

实现状态

已验证 baseline

Online runtime

Direct CLI、gateway、built-in tools、checker boundaries、backend registry 和 provider contracts 已经具备基础覆盖。

进行中

Memory system

Track 2 已把 working memory 和 Hippo 定义为并行分支；五类 action 的 Hippo controller、metadata-typed profile memory、procedural tool memory 和 selected sleep samples 是当前设计方向。

计划中

Sleep pipeline

Training / evaluation 目前仍是 scaffold。下一步应该先写 design issue，而不是直接实现。