企业官网建设流程全解析

为沙箱编码 Agent 注入持久记忆：Cognee Docker Sandbox Kit 全解

【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee

本指南围绕仓库中的 examples/integrations/docker-sandbox-kit 展开，讲解如何用一份可堆叠的 Docker Sandboxes mixin kit（cognee-memory），在deny-all网络策略下为任何沙箱化编码 Agent 提供由 cognee 知识图谱驱动的持久化、可自我进化的长期记忆。读完本文，你将掌握 kit 的完整配置语义、一次性初始化流程、单 Agent 与多 Agent 场景下的remember / recall / improve / forget用法，以及基于用户权限模型（ACL）实现 Supervisor→Worker 记忆交接的完整实战方案。

Kit 是什么：一次说清定位与设计

Docker Sandboxes 提供"可定制 kit"机制，允许在沙箱创建时注入环境、凭证、网络策略与 Agent 指令。cognee-memory正是这样一个stackable mixin kit（见 cognee-memory/spec.yaml，kind: mixin），它在沙箱内部完全嵌入式地运行 cognee 记忆层——不需要外部数据库服务，一切状态都保存在沙箱内：

• 通过uv tool install cognee在沙箱创建时安装cognee-cli（依赖uv，Docker 默认沙箱镜像自带）；
• 将所有记忆状态固定到/home/agent/.cognee（DATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORY），从而在沙箱重启后依然存活；
• 在deny-all基线策略下，仅放行 cognee 实际需要的域名（该清单是作者在deny-all下运行并阅读sbx policy log得出的）；
• 声明一个由代理托管的凭证cognee-openai（刻意不叫openai，避免与内置 Agent kit 冲突导致组合失败）；
• 固定ENABLE_BACKEND_ACCESS_CONTROL=true（cognee 默认值），启用多租户 ACL 与"按用户+数据集"的数据库隔离；
• 把使用说明追加进 Agent 记忆文件kits-memory/cognee-memory.md，引导 Agent 在任务开始recall、工作中remember、以及执行多 Agent 交接模式。

该 kit 已使用sbx v0.39.0在deny-all网络策略下端到端验证通过。

spec.yaml 深度拆解：每个字段背后的含义

spec.yaml 是 kit 的灵魂，按区块逐一看：

元信息与堆叠兼容性

schemaVersion: "2" kind: mixin name: cognee-memory version: 0.1.0 displayName: Cognee Memory description: Persistent AI memory for sandboxed agents — knowledge graph + vector search via cognee

kind: mixin意味着它可以叠加在任意 Agent kit 之上（claude、opencode等），只要沙箱创建时用--kit指向它。

environment.variables：记忆落盘与模型配置

environment: variables: DATA_ROOT_DIRECTORY: /home/agent/.cognee/data SYSTEM_ROOT_DIRECTORY: /home/agent/.cognee/system LLM_MODEL: openai/gpt-5-mini TELEMETRY_DISABLED: "1" ENABLE_BACKEND_ACCESS_CONTROL: "true"

• DATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORY：cognee 把向量库（默认 LanceDB）与图数据库（默认 kuzu/ladybug）以及关系型元数据库（SQLite）都放在这里，统一固定路径便于备份、迁移与检查；
• LLM_MODEL：默认openai/gpt-5-mini，用于实体抽取与向量嵌入；
• TELEMETRY_DISABLED：关闭遥测上报；
• ENABLE_BACKEND_ACCESS_CONTROL：多租户 ACL 与"按用户+数据集"数据库隔离的总开关。虽然这是 cognee 默认值，kit 中显式固定它，让"权限隔离"成为沙箱的既定事实。它支持的默认后端组合是 kuzu/ladybug 图库 + LanceDB 向量库，也支持 Neo4j、Postgres（demo）、Turso；不支持Neptune、ladybug-remote、Neptune Analytics（该说明在 spec.yaml 与 README 中均有强调）。

credentials：为什么叫 cognee-openai 而不叫 openai

credentials: - service: cognee-openai description: OpenAI API key used by cognee for entity extraction and embeddings required: false apiKey: name: LLM_API_KEY proxyManaged: true inject: - domain: api.openai.com scheme: bearer

两个关键点：

1. 命名规避组合冲突：内置的 shell/claude 等 kit 已经声明了openai这类常见 LLM 服务，如果两个 kit 声明同一个 service，组合会失败。因此这里使用cognee-openai。
2. proxyManaged: true+ 按域注入：真实密钥永远不进入沙箱。沙箱内 Agent 只看到占位符值（proxy-managed或sbx-cs-…），沙箱代理在请求api.openai.com时把Authorization: Bearer头替换为真实密钥。required: false保证即使未绑定凭证，沙箱创建也不会失败。

permissions.network：deny-all 下的精确放行

permissions: network: allow: - api.openai.com - pypi.org - files.pythonhosted.org - extension.ladybugdb.com - raw.githubusercontent.com

清单全部有据可查：

• api.openai.com：LLM 调用；
• pypi.org/files.pythonhosted.org：uv tool install cognee安装依赖；
• extension.ladybugdb.com：ladybug（cognee 的内嵌图数据库）首次使用时拉取扩展；
• raw.githubusercontent.com：litellm 拉取其模型成本表。

README 明确指出：该清单是在 deny-all 下运行后阅读sbx policy log推导的，这也是任何 kit 作者推导网络白名单的推荐方法。

setup.install：创建期安装动作

setup: install: - command: "mkdir -p /home/agent/.cognee/data /home/agent/.cognee/system" user: "1000" description: Create memory storage directories - command: "uv tool install cognee" user: "1000" description: Install the cognee CLI (embedded SQLite + LanceDB + Kuzu, no services needed)

以 UID 1000（agent 用户）执行，先建目录再装 CLI。安装的是完整 cognee CLI，其子命令注册于 cli/_cognee.py，包括remember、recall、improve、forget等。

agentInstructions：写给 Agent 自己的记忆手册

agentInstructions: content: | ## Persistent memory (cognee) ...

这段内容以 Markdown 追加到kits-memory/cognee-memory.md，是 Agent 在沙箱内直接可读的使用规范：

• cognee-cli remember "text, a file path, or a URL"——存储知识；
• cognee-cli recall "your question"——查询记忆；
• cognee-cli improve——富化/索引；
• cognee-cli forget --all——删除（无确认提示，慎用）；
• 推荐工作流：任务开始先recall拉取历史经验 → 工作中把项目约定、决策与原因、坑点、用户偏好等持久事实remember下来 → 不要存储密钥、凭证或一次性会话细节；
• 明确提醒：首次remember会构建知识图谱（涉及数次 LLM 调用），比普通键值写入明显更慢；recall从图谱作答。

一次性初始化：从安装 sbx 到注入密钥

在 README.md 的 Setup 一节，完整初始化命令如下：

$ brew trust docker/tap && brew install docker/tap/sbx $ sbx daemon start # own terminal, or: nohup sbx daemon start & $ sbx login # browser OAuth $ sbx policy init deny-all # strictest baseline; the kit's allowlist is the only egress $ sbx secret set-custom --host api.openai.com --env LLM_API_KEY --value "$LLM_API_KEY"

set-custom会打印一个占位符（形如sbx-cs-…，可用sbx secret ls查询）。沙箱内只看到占位符，代理在请求api.openai.com时用真实密钥替换。这套流程也完整复刻在 demo/handover.sh 的开头注释中，作为 demo 的前置条件。

单 Agent 使用：给 Agent 装上长期记忆

创建带持久记忆的沙箱只需把--kit指向 kit 目录：

$ sbx run claude --kit ./cognee-memory # agent with persistent memory $ sbx run shell --kit ./cognee-memory # or a plain shell sandbox

沙箱内 Agent 拥有完整的cognee-cli remember / recall / improve / forget能力。若要在无头（headless）的sbx exec场景中使用，需要把LLM_API_KEY显式设置为占位符（kit 中proxy-managed的 env 值服务于交互式凭证绑定路径，无头场景不适用）：

$ sbx exec <sandbox> -- sh -lc 'export LLM_API_KEY=<placeholder> LOG_LEVEL=ERROR; \ cognee-cli remember "fact worth keeping"'

CLI 细节：remember 与 recall 的可用参数

从源码看，remember命令（cli/commands/remember_command.py）本质是"add + cognify"的合并：先摄入数据，再自动加工为结构化知识图谱。支持参数包括：--dataset-name/-d（默认main_dataset）、--chunk-size（每块最大 token 数，缺省自动计算）、--chunker（TextChunker默认，可选LangchainChunker、CsvChunker）、--background/-b（后台执行 cognify）、--chunks-per-batch、--dry-run（只估算 LLM token 用量与成本，不实际摄入）、--sample-data（摄入内置 quickstart 样例做冒烟测试）。

recall命令（cli/commands/recall_command.py）是面向记忆的search别名：--query-type/-t（默认HYBRID_COMPLETION）、--datasets/-d（限定数据集）、--top-k/-k（默认 10）、--system-prompt、--session-id/-s（单独使用且不带-d/-t时直接按关键词搜索会话缓存）、--output-format/-f（pretty/json/simple）。

多 Agent 演示：Supervisor → Worker 记忆交接

README 的 Multi-agent demo 部分描述了一个在两个真实沙箱之间进行的往返交接：两个沙箱都从该 kit 创建，共享demo/目录作为工作区。cognee 状态在每个阶段运行于各自 VM 的本地磁盘（内嵌 LanceDB 无法在共享的 virtiofs 工作区挂载点上运行，这是实战中踩坑得出的结论），并以快照形式用sbx cp在沙箱间交接——记忆交接是字面意义上的"搬运"。宿主机在阶段之间于demo/cognee-state/持有权威快照。尽管 worker 收到了整个快照，supervisor 与 worker 是 cognee 中不同的用户，ACL 依然严格管控双方各自的读写范围。

三阶段往返流程

编排脚本 demo/handover.sh 依次执行三个阶段：

1. brief（cognee-supervisor沙箱）：在自己的数据集里存入一条私有笔记和一份交接简报，通过authorized_give_permission_on_datasets(...)授予 worker 对简报数据集的read + write（创建者自动持有share），并写出交接令牌demo/handover-out/handover_token.json，携带数据集 UUID。
2. work（cognee-worker沙箱）：用令牌赎回——cognee.recall(..., dataset_ids=[uuid], user=worker)。交接只能通过 UUID：数据集名按用户命名空间隔离，名字永远不会跨用户边界（负向验证：私有数据集抛PermissionDeniedError403；用名字访问共享数据集得到 404）。随后 worker 把完成报告写回共享数据集（cognee.remember(..., dataset_id=uuid, user=worker)）。
3. review（cognee-supervisor沙箱）：召回 worker 的报告。

阶段严格串行——快照在移动，从不实时共享。核心逻辑脚本 demo/supervisor_worker_handover.py 是自包含的：把它粘到任何装有 cognee 的仓库里即可运行python supervisor_worker_handover.py（进程内完成全部阶段），或用--phase brief|work|review拆分到不同环境执行。

运行与收尾：

$ export LLM_API_KEY=sk-... # only needed the first time, for the secret $ ./demo/handover.sh $ sbx policy log # the audit trail: per-domain allow/deny

清理：sbx rm -f cognee-supervisor cognee-worker && rm -rf demo/cognee-state demo/handover-out

handover.sh 的关键机制

脚本（demo/handover.sh）值得注意的细节：

• 用sbx secret ls自动提取占位符（awk '$3 == "LLM_API_KEY" {print $4}'），缺失时给出明确的创建提示并退出；
• 沙箱不存在时用sbx run shell --kit "$KIT" --name "$name" --detached .创建（kit 安装发生在 VM 内部）；
• 每个阶段：sbx cp把快照拷进沙箱 → 由于sbx cp保留宿主机属主（宿主机 uid），需要sudo chown -R agent:agent重新归属 → 通过sh -lc设置LLM_API_KEY=<占位符> LOG_LEVEL=ERROR ENABLE_BACKEND_ACCESS_CONTROL=true以及指向 VM 本地路径的DATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORY→ 用 kit 安装出的 Python 解释器（/home/agent/.local/share/uv/tools/cognee/bin/python）执行supervisor_worker_handover.py --phase …→ 再把快照拷回宿主机demo/cognee-state/。

supervisor_worker_handover.py 的权限验证细节

supervisor_worker_handover.py 用os.environ.setdefault("ENABLE_BACKEND_ACCESS_CONTROL", "true")在导入 cognee 之前固定鉴权姿势（cognee 的鉴权姿态在导入时解析）。其负向验证精确对应 README 的描述：

• worker 用_private_dataset_id访问 supervisor 的私有数据集 → 断言必须抛出PermissionDeniedError（来自 modules/users/exceptions）；
• worker 用datasets=["handover"]（名字）访问共享数据集 → 断言必须失败（名称解析不跨用户）。

之后 worker 用cognee.remember(WORKER_REPORT, dataset_id=dataset_id, user=worker)完成跨属主写回——再次强调：跨用户必须用 UUID。

用户权限模型：谁当前支持什么

README 的 "User permissioning" 一节明确了当前能力边界：

• 每个数据集的权限有read/write/delete/share四种；用户与授权的管理目前仅限 Python-SDK/REST——cognee-cli没有用户/权限命令；
• 支持"按用户+数据集"数据库隔离的后端，权威清单在 infrastructure/databases/dataset_database_handler/supported_dataset_database_handlers.py：
  • 图库：ladybug/kuzu（默认）、Neo4j（含多库版与neo4j_community每数据集一容器的 handler）、Postgres（demo）、Turso；
  • 向量：LanceDB（默认）、PGVector、Turso；
  • 不支持：Neptune、ladybug-remote、Neptune Analytics，以及未注册 dataset-database handler 的社区向量适配器。

"数据集名永不跨用户"的底层原因见 modules/data/methods/get_unique_dataset_id.py：数据集 ID 由uuid5(NAMESPACE_OID, f"{dataset_name}{user.id}{user.tenant_id}")派生（兼容模式下为uuid5(NAMESPACE_OID, f"{dataset_name}{user.id}")），同一名字对不同用户会解析为不同 UUID，因此跨用户共享只能传递 UUID。

检查记忆与安全：如何验证一切正常

README 提供了一套现成的巡检命令：

$ sbx exec cognee-supervisor -- sh -lc 'echo $LLM_API_KEY' # "proxy-managed" — never a real key $ sbx exec cognee-supervisor -- curl -s -o /dev/null -w "%{http_code}" https://example.com # 403: deny-all $ sbx policy log # every allow/deny decision $ ls demo/cognee-state/system/databases/<owner-user-uuid>/ # <dataset-uuid>.lbug + .lance.db per dataset

要点：

• 沙箱内echo $LLM_API_KEY只显示proxy-managed，证明真实密钥从未进入沙箱；
• 对沙箱外域名curl返回 403，证明deny-all基线生效；
• sbx policy log提供每个域名的 allow/deny 审计轨迹；
• 每个数据集在磁盘上表现为独立的<dataset-uuid>.lbug（图）与.lance.db（向量）文件，按属主用户 UUID 分目录存放；
• 关系型元数据库（demo/cognee-state/system/databases/cognee_db，SQLite）保存用户、数据集与 ACL 行——demo 跑完后，worker 对共享数据集恰好持有read、write两条授权，对私有数据集零授权。

目录布局速览

docker-sandbox-kit/ ├── cognee-memory/ # the kit — point --kit here │ └── spec.yaml ├── demo/ │ ├── handover.sh # 2 real sandboxes, permissioned round-trip handover │ ├── handover-out/ # the JSON handover token (created at runtime) │ ├── cognee-state/ # canonical memory snapshot between phases (runtime) │ └── supervisor_worker_handover.py └── README.md

注意事项与扩展路径

README 的 Notes 给出了三条重要提示：

1. 性能预期：remember会构建知识图谱（数次 LLM 调用），首次写入明显慢于普通键值存储；recall从图谱作答。improve（cli/commands/improve_command.py）可进一步富化索引。
2. 更换 LLM Provider：kit 默认openai/gpt-5-mini。要换其他 provider，需要同时修改environment.variables、credentials/permissions.network区块以及已存储的 secret——三者必须配套调整。
3. 跨沙箱的常驻记忆：如果需求是"常驻在线、并发 Agent、无共享工作区"，不要共享嵌入式存储，而应运行一个中心化 cognee API server，让各沙箱通过网络白名单指向它。

小结

docker-sandbox-kit是一个高完成度的参考实现：从spec.yaml的精简白名单与代理托管凭证，到handover.sh基于快照搬运 +supervisor_worker_handover.py基于 UUID 与 ACL 的跨用户交接，完整覆盖了"沙箱内嵌记忆"从配置到安全审计的全部环节。对于希望让编码 Agent 拥有跨会话、跨 Agent 持久记忆的团队，这份 kit 既是可直接--kit引用的工件，也是一份值得逐行研读的集成范本。

【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee