mcpField
D
deep-agents-memory

deep-agents-memory

github.com/langchain-aiAgent 工作流1.3k19.2k 次安装3 天前更新
代码仓库

关于 deep-agents-memory

deep-agents-memory 介绍 Deep Agents 的文件与记忆后端配置，帮助开发者选择线程内临时文件、跨会话存储或本地文件访问，并说明路径路由与访问限制。

主要功能

  1. 01StateBackend 按线程保存文件
  2. 02StoreBackend 跨会话保存记忆
  3. 03CompositeBackend 按路径路由
  4. 04提供文件操作工具
  5. 05通过虚拟模式限制路径访问

适用场景

  1. 01在单个线程中保存临时文件
  2. 02在 Agent 会话间共享记忆
  3. 03将指定路径路由到持久存储
  4. 04在本地开发中审核文件变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/langchain-ai/langchain-skills --skill deep-agents-memory

安装后在 Claude Code 中输入/deep-agents-memory确认已加载。

详细介绍

Deep Agents 使用可插拔后端来执行文件操作和管理内存：

短期（StateBackend）：在单个线程内持久化，线程结束后数据会丢失 长期（StoreBackend）：跨线程和会话持久化 混合（CompositeBackend）：将不同路径路由到不同后端

FilesystemMiddleware 提供以下工具：ls、read_file、write_file、edit_file、glob、grep

用例后端原因
临时工作文件StateBackend默认选项，无需设置
本地开发 CLIFilesystemBackend可直接访问磁盘
跨会话记忆StoreBackend可跨线程持久化
混合存储CompositeBackend混合使用临时存储和持久化存储
默认的 StateBackend 会在线程内临时存储文件。 
from deepagents import create_deep_agent

agent = create_deep_agent()  # Default: StateBackend
result = agent.invoke({
    "messages": [{"role": "user", "content": "Write notes to /draft.txt"}]
}, config={"configurable": {"thread_id": "thread-1"}})
# /draft.txt is lost when thread ends
默认的 StateBackend 会在线程内临时存储文件。 
import { createDeepAgent } from "deepagents";

const agent = await createDeepAgent();  // Default: StateBackend
const result = await agent.invoke({
  messages: [{ role: "user", content: "Write notes to /draft.txt" }]
}, { configurable: { thread_id: "thread-1" } });
// /draft.txt is lost when thread ends
配置 CompositeBackend，将不同路径路由到不同的存储后端。 
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

composite_backend = lambda rt: CompositeBackend(
    default=StateBackend(rt),
    routes={"/memories/": StoreBackend(rt)}
)

agent = create_deep_agent(backend=composite_backend, store=store)

# /draft.txt -> ephemeral (StateBackend)
# /memories/user-prefs.txt -> persistent (StoreBackend)
配置 CompositeBackend，将不同路径路由到不同的存储后端。 
import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
import { InMemoryStore } from "@langchain/langgraph";

const store = new InMemoryStore();

const agent = await createDeepAgent({
  backend: (config) => new CompositeBackend(
    new StateBackend(config),
    { "/memories/": new StoreBackend(config) }
  ),
  store
});

// /draft.txt -> ephemeral (StateBackend)
// /memories/user-prefs.txt -> persistent (StoreBackend)
通过 StoreBackend 路由，/memories/ 中的文件会跨线程持久化。 
# Using CompositeBackend from previous example
config1 = {"configurable": {"thread_id": "thread-1"}}
agent.invoke({"messages": [{"role": "user", "content": "Save to /memories/style.txt"}]}, config=config1)

config2 = {"configurable": {"thread_id": "thread-2"}}
agent.invoke({"messages": [{"role": "user", "content": "Read /memories/style.txt"}]}, config=config2)
# Thread 2 can read file saved by Thread 1
通过 StoreBackend 路由，/memories/ 中的文件会跨线程持久化。 
// Using CompositeBackend from previous example
const config1 = { configurable: { thread_id: "thread-1" } };
await agent.invoke({ messages: [{ role: "user", content: "Save to /memories/style.txt" }] }, config1);

const config2 = { configurable: { thread_id: "thread-2" } };
await agent.invoke({ messages: [{ role: "user", content: "Read /memories/style.txt" }] }, config2);
// Thread 2 can read file saved by Thread 1
使用 FilesystemBackend 进行本地开发，可直接访问真实磁盘并支持人工介入。 
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),  # Restrict access
    interrupt_on={"write_file": True, "edit_file": True},
    checkpointer=MemorySaver()
)

# Agent can read/write actual files on disk
使用 FilesystemBackend 进行本地开发，可直接访问真实磁盘并支持人工介入。 
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  interruptOn: { write_file: true, edit_file: true },
  checkpointer: new MemorySaver()
});

安全：切勿在 Web 服务器中使用 FilesystemBackend；请改用 StateBackend 或沙箱。

在自定义工具中直接访问存储，以执行长期记忆操作。 
from langchain.tools import tool, ToolRuntime
from langchain.agents import create_agent
from langgraph.store.memory import InMemoryStore

@tool
def get_user_preference(key: str, runtime: ToolRuntime) -> str:
    """Get a user preference from long-term storage."""
    store = runtime.store
    result = store.get(("user_prefs",), key)
    return str(result.value) if result else "Not found"

@tool
def save_user_preference(key: str, value: str, runtime: ToolRuntime) -> str:
    """Save a user preference to long-term storage."""
    store = runtime.store
    store.put(("user_prefs",), key, {"value": value})
    return f"Saved {key}={value}"

store = InMemoryStore()

agent = create_agent(
    model="gpt-4.1",
    tools=[get_user_preference, save_user_preference],
    store=store
)
### Agent 可以配置的内容
  • 后端类型和配置
  • CompositeBackend 的路由规则
  • FilesystemBackend 的根目录
  • 文件操作的人工介入机制
Agent 无法配置的内容
  • 工具名称（ls、read_file、write_file、edit_file、glob、grep）
  • 访问 virtual_mode 限制范围之外的文件
  • 未正确配置后端时跨线程访问文件
StoreBackend 需要一个 store 实例。 
# WRONG
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

# CORRECT
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())
StoreBackend 需要一个 store 实例。 
// WRONG
const agent = await createDeepAgent({ backend: (c) => new StoreBackend(c) });

// CORRECT
const agent = await createDeepAgent({ backend: (c) => new StoreBackend(c), store: new InMemoryStore() });
StateBackend 文件的作用范围限定在线程内——请使用相同的 thread_id，或使用 StoreBackend 实现跨线程访问。 
# WRONG: thread-2 can't read file from thread-1
agent.invoke({"messages": [...]}, config={"configurable": {"thread_id": "thread-1"}})  # Write
agent.invoke({"messages": [...]}, config={"configurable": {"thread_id": "thread-2"}})  # File not found!
StateBackend 文件的作用范围限定在线程内——请使用相同的 thread_id，或使用 StoreBackend 实现跨线程访问。 
// WRONG: thread-2 can't read file from thread-1
await agent.invoke({ messages: [...] }, { configurable: { thread_id: "thread-1" } });  // Write
await agent.invoke({ messages: [...] }, { configurable: { thread_id: "thread-2" } });  // File not found!
路径必须匹配 CompositeBackend 的路由前缀，才能实现持久化。 
# With routes={"/memories/": StoreBackend(rt)}:
agent.invoke(...)  # /prefs.txt -> ephemeral (no match)
agent.invoke(...)  # /memories/prefs.txt -> persistent (matches route)
路径必须匹配 CompositeBackend 的路由前缀，才能实现持久化。 
// With routes: { "/memories/": StoreBackend }:
await agent.invoke(...);  // /prefs.txt -> ephemeral (no match)
await agent.invoke(...);  // /memories/prefs.txt -> persistent (matches route)
生产环境请使用 PostgresStore（InMemoryStore 会在重启后丢失）。 
# WRONG                              # CORRECT
store = InMemoryStore()              store = PostgresStore(connection_string="postgresql://...")
生产环境请使用 PostgresStore（InMemoryStore 会在重启后丢失）。 
// WRONG                                    // CORRECT
const store = new InMemoryStore();          const store = new PostgresStore({ connectionString: "..." });
启用 virtual_mode=True 以限制路径访问（防止通过 ../ 和 ~/ 路径逃逸）。 
backend = FilesystemBackend(root_dir="/project", virtual_mode=True)  # Secure
CompositeBackend 会优先匹配最长前缀。 
routes = {"/mem/": StoreBackend(rt), "/mem/temp/": StateBackend(rt)}
# /mem/file.txt -> StoreBackend, /mem/temp/file.txt -> StateBackend (longer match)

评论

支持 Markdown