Deep Agents Day 8: Using Memory and Permissions to Keep Agents Within Boundaries

Conclusion

Do not mix memory and permissions; they serve different purposes.

memory provides long‑term contextual prompts, while permissions enforce hard tool boundaries.

Writing “do not read secrets” in memory helps but is insufficient; true prevention requires permissions, sandboxing, and audit logging.

1. Memory Is Not Chat History

In Deep Agents the memory parameter does not store chat logs. It receives a list of file paths (e.g., AGENTS.md) that MemoryMiddleware loads before runtime and injects into the system prompt as long‑term project rules.

Typical rules stored in AGENTS.md:

How to run tests in the repository

Code‑style conventions

Directories that must not be modified

User‑preferred output formats

Team review standards

from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

backend = FilesystemBackend(
    root_dir="./agent-data",
    virtual_mode=True,
)

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    backend=backend,
    memory=["/memory/AGENTS.md"],
)

This code shows that at agent startup the file /memory/AGENTS.md is read from the backend and its contents are placed into the system prompt. If the agent learns a stable preference, the memory file can be updated via the file tool.

2. Memory Persistence Depends on Backend

The memory=[...] list only tells the agent which files to read; it does not guarantee persistence. Persistence depends on the chosen backend: StateBackend: stores files in LangGraph state – suitable for demos and tests. FilesystemBackend: writes files to local disk – suitable for personal development tools. StoreBackend: uses LangGraph Store – suitable for multi‑instance services. CompositeBackend: allows /memory/ and /workspace/ to use different storage backends.

Chat history and memory are distinct concepts.

3. What Belongs in Memory

Example AGENTS.md snippet (stable, reusable, low‑sensitivity information):

# Project Rules
- Default test command: `uv run pytest`
- Review API changes only after checking `tests/`
- Output explanations in Chinese, keep code comments in English
- Do not read `.env`, `secrets/`, or production DB connection strings

Suitable items:

Test commands

Code‑style guidelines

Review standards

Output‑format preferences

Common directory explanations

Unsuitable items:

API keys, access tokens, database passwords

Transient information relevant only to the current task

Unverified user privacy data

Unvalidated business conclusions

4. Permissions Govern File Tools

Permissions are expressed with FilesystemPermission. Example configuration:

from deepagents.middleware.permissions import FilesystemPermission

permissions = [
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/src/**", "/workspace/tests/**"],
        mode="allow",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/workspace/.env", "/workspace/secrets/**"],
        mode="deny",
    ),
    FilesystemPermission(
        operations=["read", "write"],
        paths=["/**"],
        mode="deny",
    ),
]

Key facts:

Only read and write operations are supported; they map to file‑system actions such as ls/read_file/glob/grep and write_file/edit_file.

Rules are matched in declaration order; the first matching rule applies.

If no rule matches, the default is to allow, so a final deny rule is recommended.

The current version does not block execute. If the backend permits shell execution, sandboxing, human‑in‑the‑loop (HITL) review, and audit logging are required.

5. Combining Memory and Permissions

Typical project configuration (path → mechanism → purpose): /memory/AGENTS.md – memory – team rules, test commands, output preferences /workspace/src/** – permissions allow – read/write business code /workspace/tests/** – permissions allow – read/write tests /workspace/.env – permissions deny – prevent read/write of credentials /workspace/secrets/** – permissions deny – prevent read/write of secret files execute – HITL + sandbox – manual approval and isolation for command execution

Thus:

Memory stores “what should be done”.

Permissions store “what the tools may do”.

Sandbox limits “where commands run”.

Audit logs record “what actually happened”.

6. Configuration Blueprint for a Team Code Assistant

Write stable rules, test commands, and review standards into /memory/AGENTS.md.

Allow read/write of /workspace/src/** and /workspace/tests/** via permissions.

Deny access to .env, secrets/, .git/, and build‑artifact directories.

Execute commands only inside a sandbox or CI runner.

Require HITL approval for edit_file and execute actions.

Log all tool calls, commands, durations, and exit codes for audit.

This layered approach lets the agent know team rules at startup while keeping hard boundaries at the tool and execution‑environment layers.