记忆按层写入 API

wesgine 记忆系统的按层写入设计——写、清、取单条都按层提问。

设计原则

用户面的每个动词只收 layer，不收 scope。

引擎内部通过 LayerTarget(layer) 将层名转换为存储参数。

写入（SaveToLayer）

POST /cells/{id}/memory
Body: { "layer": "about_me", "content": "...", ... }

LayerTarget(layer) 决定三件事：

决定说明
Scope落到哪个存储分区
要不要 actor共享层不带 actor
Namespace命名空间谁给

层写入规则

层可写约束
environment❌ErrLayerNotWritable——宿主感知器产出
consensus✅需 admin；带 actor → ErrLayerShared
about_me✅必须有 actor
agent_memory✅必须有 actor + namespace
session❌ErrLayerNotWritable——运行时态
working❌ErrLayerNotWritable——运行时态

四种拒绝

错误含义
ErrUnknownLayer层名不存在
ErrLayerNotWritable环境/会话/工作不允许写
ErrLayerShared共识层带了 actor
ErrLayerNamespaceRequiredagent_memory 空 namespace

清空（ClearLayer）

DELETE /cells/{id}/memory/layer?layer=about_me&actor=alice

收结构体参数，不收三个位置参数。

可清列表复用可写列表。

额外拒绝三种返回成功的 0：

取单条（GetAs）

GET /cells/{id}/memory/{entryId}?actor=alice

使用 ActorVisible 判断归属。

不属于你与不存在同返 404。

删除单条（DeleteAs）

DELETE /cells/{id}/memory/{entryId}

不属于你返回 403。

不存在返回幂等成功（nil）。

读与删的不对称

动词「不是你的」「不存在」
GetAs404404（并为一个）
DeleteAs403nil（幂等成功）

读不配得到「它确实存在」的确认。

删配得上一句拒绝。