agent-memory-demo

A minimal, file-backed memory layer for a Claude-powered agent, built per the technical article. No vector DB, no embeddings — just markdown files on disk managed through Anthropic's beta memory tool.

Files

• memory_backend.py — LocalFilesystemMemoryTool, a subclass of BetaAbstractMemoryTool that implements view/create/str_replace/insert/ delete/rename against ./memory/memories, with path-traversal guards.
• system_prompt.py — persona + memory operating rules (what to store, when to read, when to supersede).
• agent.py — terminal chat loop using client.beta.messages.tool_runner. Commands: /quit, /memory_view, /memory_clear.
• memory_defrag.py — librarian pass that audits /memories for stale or contradictory files and deletes them.
• test_backend.py — 22 unit tests exercising every backend command plus path-traversal and root-deletion guards. No API calls.
• test_persistence.py — simulates two sessions hitting the same memory root and verifies files (including a superseded fact) survive across a fresh backend instance. No API calls.
• test_live.py — full end-to-end run: session 1 gives the agent durable facts, session 2 starts with a fresh message list and asks questions only answerable from memory. Requires ANTHROPIC_API_KEY.

Setup

pip install "anthropic>=0.87.0"
export ANTHROPIC_API_KEY="sk-ant-..."

Run the agent

python agent.py

Then try a session like:

You: Hi, I'm Adedayo, a content designer. Please keep replies short.
You: My active project is memory-layer-guide.
You: /quit

Restart, and:

You: What do you remember about me?

The agent should view /memories before replying and surface your name, role, preferences, and active project.

Run the tests

python test_backend.py       # 22 unit tests, no API needed
python test_persistence.py   # 2-session simulation, no API needed
python test_live.py          # full live test, requires ANTHROPIC_API_KEY

Test results from this build

• test_backend.py: 22/22 PASS
• test_persistence.py: 7/7 PASS (file layout, nested dirs, superseding an older fact, cross-session reads)
• test_live.py: not executed in the build environment because this sandbox has no ANTHROPIC_API_KEY and the Messages API rejects OAuth tokens. Run it locally to verify end-to-end.

Notes

• The memory tool is part of Anthropic's context-management-2025-06-27 beta. If the beta header or tool type changes, update agent.py and memory_defrag.py accordingly.
• LocalFilesystemMemoryTool._validate_path is the security boundary. Every test that matters (traversal with .., paths outside /memories, deleting the root) is in test_backend.py.
• Stale memory is worse than missing memory. Run memory_defrag.py periodically, or schedule it.