`memory` Plugin

memory 为 Agent 提供长期记忆能力。Plugin 负责统一 Action、作用域和上下文规则，实际的记忆形成、存储、召回、修订与删除由一个 MemoryProvider 完成。

它提供以下 Action：

status
search
read
remember
digest
revise
forget

Provider 与 Adapter

MemoryPlugin
  -> MemoryProvider
     -> BuiltinMemoryProvider
        -> MemoryStorageAdapter
           -> FileMemoryStorageAdapter

MemoryPlugin 不读取 Workspace 文件，也不规定 Memory 的物理位置。文件、SQLite、对象存储和远程 Memory 服务都属于 Provider 背后的实现。

内建 Provider 当前使用 FileMemoryStorageAdapter。City 默认把它的数据放在：

~/.downcity/agents/<agent_id>/memory/

这个目录是 File Adapter 的实现约定，不是 @downcity/agent 的协议。可以通过 Plugin 配置的绝对 root_path 覆盖。

City 配置

启用内建 Provider 和 File Adapter：

downcity plugin enable memory <agent_id> \
  --config '{"provider":"builtin","storage":"file"}'

使用自定义本地根目录：

downcity plugin config memory <agent_id> \
  --set '{"provider":"builtin","storage":"file","root_path":"/absolute/path/to/memory"}'

配置和启用状态保存在 ~/.downcity/downcity.db，Memory 内容由 Provider 自己管理。

SDK 使用

import {
  BuiltinMemoryProvider,
  FileMemoryStorageAdapter,
  MemoryPlugin,
} from "@downcity/plugins/memory";

const memory = new MemoryPlugin({
  provider: new BuiltinMemoryProvider({
    storage: new FileMemoryStorageAdapter({
      root_path: "/absolute/path/to/agent-memory",
    }),
  }),
});

const agent = new Agent({
  id: "assistant",
  workspace,
  plugins: [memory],
});

SDK 调用方也可以直接实现 MemoryProvider，接入 Mem0、Hindsight、Graphiti 或自己的远程 Memory 服务。

Action 调用

await agent.plugins.run_action({
  plugin: "memory",
  action: "remember",
  payload: {
    content: "用户偏好简洁回答。",
    topic: "user-preferences",
    memory_type: "preference",
  },
});

查询与精确读取：

const recalled = await agent.plugins.run_action({
  plugin: "memory",
  action: "search",
  payload: {
    query: "用户回答风格偏好",
    max_results: 5,
  },
});

await agent.plugins.run_action({
  plugin: "memory",
  action: "read",
  payload: {
    memory_id: "wiki/user-preferences",
  },
});

memory_id 和 citation 都是 Provider 的逻辑标识，调用方不能将它们解释为物理文件路径。

CLI Action

运行中的 Agent 可以通过统一 Plugin Action 命令调用：

downcity plugin action memory status <agent_id>
downcity plugin action memory search <agent_id> --input '{"query":"project decision"}'
downcity plugin action memory read <agent_id> --input '{"memory_id":"wiki/project-decisions"}'
downcity plugin action memory forget <agent_id> --input '{"memory_id":"wiki/obsolete"}'

关键语义

Session 消息和 checkpoint 仍保存在 Workspace，不属于长期 Memory。
Memory Provider 是当前 Plugin 实例的唯一事实源。
Storage Adapter 只处理底层持久化，不定义召回和记忆形成语义。
Provider 返回结构化 Memory 和逻辑引用，不返回物理文件路径。
Memory 内容作为不可信历史数据进入上下文，不能获得 system instruction 权限。

memory Plugin