为沙箱编码 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 kitcognee-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.yamlkind: mixin它在沙箱内部完全嵌入式地运行 cognee 记忆层——不需要外部数据库服务一切状态都保存在沙箱内通过uv tool install cognee在沙箱创建时安装cognee-cli依赖uvDocker 默认沙箱镜像自带将所有记忆状态固定到/home/agent/.cogneeDATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORY从而在沙箱重启后依然存活在deny-all基线策略下仅放行 cognee 实际需要的域名该清单是作者在deny-all下运行并阅读sbx policy log得出的声明一个由代理托管的凭证cognee-openai刻意不叫openai避免与内置 Agent kit 冲突导致组合失败固定ENABLE_BACKEND_ACCESS_CONTROLtruecognee 默认值启用多租户 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 cogneekind: 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: trueDATA_ROOT_DIRECTORY/SYSTEM_ROOT_DIRECTORYcognee 把向量库默认 LanceDB与图数据库默认 kuzu/ladybug以及关系型元数据库SQLite都放在这里统一固定路径便于备份、迁移与检查LLM_MODEL默认openai/gpt-5-mini用于实体抽取与向量嵌入TELEMETRY_DISABLED关闭遥测上报ENABLE_BACKEND_ACCESS_CONTROL多租户 ACL 与按用户数据集数据库隔离的总开关。虽然这是 cognee 默认值kit 中显式固定它让权限隔离成为沙箱的既定事实。它支持的默认后端组合是 kuzu/ladybug 图库 LanceDB 向量库也支持 Neo4j、Postgresdemo、Turso不支持Neptune、ladybug-remote、Neptune Analytics该说明在 spec.yaml 与 README 中均有强调。credentials为什么叫 cognee-openai 而不叫 openaicredentials: - 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两个关键点命名规避组合冲突内置的 shell/claude 等 kit 已经声明了openai这类常见 LLM 服务如果两个 kit 声明同一个 service组合会失败。因此这里使用cognee-openai。proxyManaged: true 按域注入真实密钥永远不进入沙箱。沙箱内 Agent 只看到占位符值proxy-managed或sbx-cs-…沙箱代理在请求api.openai.com时把Authorization: Bearer头替换为真实密钥。required: false保证即使未绑定凭证沙箱创建也不会失败。permissions.networkdeny-all 下的精确放行permissions: network: allow: - api.openai.com - pypi.org - files.pythonhosted.org - extension.ladybugdb.com - raw.githubusercontent.com清单全部有据可查api.openai.comLLM 调用pypi.org/files.pythonhosted.orguv tool install cognee安装依赖extension.ladybugdb.comladybugcognee 的内嵌图数据库首次使用时拉取扩展raw.githubusercontent.comlitellm 拉取其模型成本表。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 1000agent 用户执行先建目录再装 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 kits allowlist is the only egress $ sbx secret set-custom --host api.openai.com --env LLM_API_KEY --value $LLM_API_KEYset-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_KEYplaceholder LOG_LEVELERROR; \ cognee-cli remember fact worth keepingCLI 细节remember 与 recall 的可用参数从源码看remember命令cli/commands/remember_command.py本质是add cognify的合并先摄入数据再自动加工为结构化知识图谱。支持参数包括--dataset-name/-d默认main_dataset、--chunk-size每块最大 token 数缺省自动计算、--chunkerTextChunker默认可选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/-fpretty/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 依次执行三个阶段briefcognee-supervisor沙箱在自己的数据集里存入一条私有笔记和一份交接简报通过authorized_give_permission_on_datasets(...)授予 worker 对简报数据集的read write创建者自动持有share并写出交接令牌demo/handover-out/handover_token.json携带数据集 UUID。workcognee-worker沙箱用令牌赎回——cognee.recall(..., dataset_ids[uuid], userworker)。交接只能通过 UUID数据集名按用户命名空间隔离名字永远不会跨用户边界负向验证私有数据集抛PermissionDeniedError403用名字访问共享数据集得到 404。随后 worker 把完成报告写回共享数据集cognee.remember(..., dataset_iduuid, userworker)。reviewcognee-supervisor沙箱召回 worker 的报告。阶段严格串行——快照在移动从不实时共享。核心逻辑脚本 demo/supervisor_worker_handover.py 是自包含的把它粘到任何装有 cognee 的仓库里即可运行python supervisor_worker_handover.py进程内完成全部阶段或用--phase brief|work|review拆分到不同环境执行。运行与收尾$ export LLM_API_KEYsk-... # 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-outhandover.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_LEVELERROR ENABLE_BACKEND_ACCESS_CONTROLtrue以及指向 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/exceptionsworker 用datasets[handover]名字访问共享数据集 → 断言必须失败名称解析不跨用户。之后 worker 用cognee.remember(WORKER_REPORT, dataset_iddataset_id, userworker)完成跨属主写回——再次强调跨用户必须用 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、Postgresdemo、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_dbSQLite保存用户、数据集与 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 给出了三条重要提示性能预期remember会构建知识图谱数次 LLM 调用首次写入明显慢于普通键值存储recall从图谱作答。improvecli/commands/improve_command.py可进一步富化索引。更换 LLM Providerkit 默认openai/gpt-5-mini。要换其他 provider需要同时修改environment.variables、credentials/permissions.network区块以及已存储的 secret——三者必须配套调整。跨沙箱的常驻记忆如果需求是常驻在线、并发 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考