deep-agents-memory

Deep Agents は、ファイル操作とメモリにプラグイン可能なバックエンドを使用します。

短期（StateBackend）：単一のスレッド内で保持され、スレッド終了時に失われます 長期（StoreBackend）：スレッドやセッションをまたいで保持されます ハイブリッド（CompositeBackend）：異なるパスを異なるバックエンドに振り分けます

FilesystemMiddleware は次のツールを提供します：ls、read_file、write_file、edit_file、glob、grep

用途	バックエンド	理由
一時的な作業ファイル	StateBackend	デフォルトで、セットアップ不要
ローカル開発用 CLI	FilesystemBackend	ディスクに直接アクセス
セッションをまたぐメモリ	StoreBackend	スレッドをまたいで保持
ハイブリッドストレージ	CompositeBackend	一時的なストレージと永続ストレージを組み合わせる

デフォルトの StateBackend は、スレッド内でファイルを一時的に保存します。 ```python 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

</python>
<typescript>
デフォルトの StateBackend は、スレッド内でファイルを一時的に保存します。
```typescript
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 を設定して、パスを異なるストレージバックエンドに振り分けます。 ```python 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)

</python>
<typescript>
CompositeBackend を設定して、パスを異なるストレージバックエンドに振り分けます。
```typescript
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)

/memories/ 内のファイルは、StoreBackend による振り分けを通じてスレッドをまたいで保持されます。 ```python # 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

</python>
<typescript>
/memories/ 内のファイルは、StoreBackend による振り分けを通じてスレッドをまたいで保持されます。
```typescript
// 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 を使用します。 ```python 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

</python>
<typescript>
実際のディスクアクセスと人間の介入を伴うローカル開発には、FilesystemBackend を使用します。
```typescript
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()
});

セキュリティ：ウェブサーバーでは FilesystemBackend を使用しないでください。代わりに StateBackend またはサンドボックスを使用してください。

長期メモリ操作のために、カスタムツールからストアに直接アクセスします。 ```python 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 )

</python>
</ex-store-in-custom-tools>

<boundaries>
### エージェントが設定できること

- バックエンドの種類と設定
- CompositeBackend の振り分けルール
- FilesystemBackend のルートディレクトリ
- ファイル操作における人間の介入

### エージェントが設定できないこと

- ツール名（ls、read_file、write_file、edit_file、glob、grep）
- virtual_mode の制限外にあるファイルへのアクセス
- 適切なバックエンド設定なしでのスレッドをまたぐファイルアクセス
</boundaries>

<fix-storebackend-requires-store>
<python>
StoreBackend にはストアのインスタンスが必要です。
```python
# WRONG
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

# CORRECT
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())

StoreBackend にはストアのインスタンスが必要です。 ```typescript // WRONG const agent = await createDeepAgent({ backend: (c) => new StoreBackend(c) });

// CORRECT const agent = await createDeepAgent({ backend: (c) => new StoreBackend(c), store: new InMemoryStore() });

</typescript>
</fix-storebackend-requires-store>

<fix-statebackend-files-dont-persist>
<python>
StateBackend のファイルはスレッド単位です。スレッドをまたいでアクセスするには、同じ thread_id を使用するか、StoreBackend を使用してください。
```python
# 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 を使用してください。 ```typescript // 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 のルートプレフィックスと一致している必要があります。 ```python # With routes={"/memories/": StoreBackend(rt)}: agent.invoke(...) # /prefs.txt -> ephemeral (no match) agent.invoke(...) # /memories/prefs.txt -> persistent (matches route) ``` 永続化するには、パスが CompositeBackend のルートプレフィックスと一致している必要があります。 ```typescript // With routes: { "/memories/": StoreBackend }: await agent.invoke(...); // /prefs.txt -> ephemeral (no match) await agent.invoke(...); // /memories/prefs.txt -> persistent (matches route) ``` 本番環境では PostgresStore を使用してください（InMemoryStore は再起動時にデータが失われます）。 ```python # WRONG # CORRECT store = InMemoryStore() store = PostgresStore(connection_string="postgresql://...") ``` 本番環境では PostgresStore を使用してください（InMemoryStore は再起動時にデータが失われます）。 ```typescript // WRONG // CORRECT const store = new InMemoryStore(); const store = new PostgresStore({ connectionString: "..." }); ``` virtual_mode=True を有効にして、パスへのアクセスを制限してください（../ や ~/ による範囲外へのアクセスを防ぎます）。 ```python backend = FilesystemBackend(root_dir="/project", virtual_mode=True) # Secure ``` CompositeBackend は、最長のプレフィックスを優先して照合します。 ```python routes = {"/mem/": StoreBackend(rt), "/mem/temp/": StateBackend(rt)} # /mem/file.txt -> StoreBackend, /mem/temp/file.txt -> StateBackend (longer match) ```