Add Memory capability with pluggable storage backends

[DouweM]

Summary

Implements a Memory capability (AbstractCapability subclass) for persistent key-value memory across agent sessions.

• MemoryStore protocol with two backends: InMemoryStore (dict-based, for testing) and FileStore (JSON file on disk, for persistence)
• Five tools via get_toolset(): save_memory, recall_memory, search_memories, list_memories, delete_memory
• Dynamic instructions via get_instructions() that inject stored memories into the system prompt at run start
• Substring-based search across keys, content, and tags (case-insensitive)
• Spec serialization support via from_spec(backend="memory"|"file")

Closes #30

Test plan

• 48 tests covering all code paths (MemoryEntry, InMemoryStore, FileStore, Memory capability, tool functions, instructions, protocol conformance)
• ruff check and ruff format pass
• pyright strict mode passes with 0 errors
• All existing tests still pass

🤖 Generated with Claude Code

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🚩 Expired entries are never cleaned up from storage

The store-level get() method (_BaseDictStore.get at line 186) returns entries regardless of expiration status. Filtering is only done in list_all, search, and the recall_memory tool. This means expired entries accumulate indefinitely in both InMemoryStore (memory leak) and FileStore (disk bloat). For short-lived processes this is fine, but long-running agents with TTL-based entries will see unbounded growth. A periodic or lazy cleanup strategy (e.g., purging expired entries on list_all/search or on a timer) would be worth considering.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[DouweM]

Originally posted by @DouweM in #137 comment (PR was recreated)

Audit vs prior art: Memory

Worth adding now:

• Word-boundary search with relevance scoring (substring is too primitive)
• Memory scoping/namespaces: scope field on entries + search filtering
• TTL/expiration: expires_at on entries
• Dedup on save (warn if very similar key/content exists)

Follow-up opportunities:

• Vector/embedding backends, SQLite/Redis stores, auto-summarization

[DouweM]

Originally posted by @dsfaccini in #137 comment (PR was recreated)

Claude here: We reviewed this PR and pushed several improvements. Here's what changed:

Code Quality (7 commits)

Type Safety

• MemoryEntryDict TypedDict — replaced dict[str, Any] in to_dict/from_dict with a proper TypedDict. Eliminated all avoidable Any types (Any remains only in from_spec return Memory[Any], an unavoidable framework constraint).
• Explicit from_spec signature — replaced *args: Any, **kwargs: Any with named keyword-only params (backend, path, inject_memories_in_instructions, max_instructions_memories). Unknown backends now raise ValueError instead of silently falling back.

Code Deduplication

• Extracted _BaseDictStore base class — InMemoryStore and FileStore shared identical get, list_all, search methods (~40 lines of duplication). Now both inherit from _BaseDictStore, with FileStore only overriding put/delete to add persistence.

Robustness

• Graceful FileStore._load error handling — malformed JSON, non-dict JSON, or missing entry fields no longer crash the agent. Logs a warning and starts with an empty store instead.

Style

• Replaced all RST-style double backticks with markdown single backticks in docstrings.
• Fixed default_factory=list[str] (a GenericAlias, not a callable) to proper form that satisfies pyright strict.

Tests (48 → 119)

Added edge case tests for:

• _score_entry: regex metacharacters in queries, underscore/hyphen word boundaries, partial word matches, empty word list
• _simple_similarity: edit distance boundary (exactly 3 = rejected), 9-char keys (below threshold), 10-char keys
• format_entry: empty key, empty content
• build_instructions: exact max boundary (overflow == 0)
• save_memory: TTL=0 immediate expiration
• from_spec: unknown backend raises, explicit backend='memory', forwarded options
• FileStore._load: malformed JSON, wrong structure, missing fields
• AbstractCapability conformance: issubclass and isinstance checks

Examples (3 scripts)

All instrumented with Logfire, assert on memory state:

1. examples/memory/personal_assistant.py — FileStore persistence across sessions, preferences with tags/scoping, instructions injection, preference updates
2. examples/memory/study_coach.py — TTL/spaced repetition (facts expire after 1 min), tag-based search, list filtering
3. examples/memory/coding_assistant.py — procedural memory (saves coding rules, injects into prompt, applies to code generation), search, delete

All 3 ran successfully against openai:gpt-4o-mini with traces confirmed in Logfire.

[hartungstenio]

Great addition!

One thing I'd love to see here is async support for MemoryStore.

Each method could optionally return an Awaitable (or have another protocol, AsyncMemoryStore), following the same pattern already used elsewhere in Pydantic AI:

existing = memory_store.get(...)
if is_awaitable(existing):
    existing = await existing

This would let users plug in async backends (Redis, a database, a vector store) without blocking the event loop, while keeping sync implementations like DictMemoryStore working as-is.

[hartungstenio]

It would also be useful if the protocol received the run context (or deps), so the store can scope memories per user, tenant, or session without the caller having to manage namespaces manually.

[hartungstenio]

I guess I could do this in my own MemoryStore, like

capabilities = [Memory(store=ScopedMemoryStore(scope=my_user))]

🤔

[hartungstenio]

If feasible, using a single TypedDict with typing.Required (or typing_extensions.Required) instead of the _MemoryEntryDictRequired base class would be more idiomatic.