Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion python/packages/core/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -337,7 +337,7 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID

- **`FileMemoryProvider`** - `ContextProvider` that gives an agent a session-scoped, file-based memory backed by the same `AgentFileStore` abstraction. Adds tools (`file_memory_write`, `file_memory_read`, `file_memory_delete`, `file_memory_ls`, `file_memory_grep`, `file_memory_replace`, `file_memory_replace_lines`) plus default usage instructions. Port of the .NET `FileMemoryProvider`.
- **Scoping** - Memories are isolated per session by default: each session writes under a working folder derived from `context.session_id`. Pass an explicit `scope` (e.g. a user id) to group memories across sessions, mirroring `FoundryMemoryProvider`'s `scope` arg. The scope (or session id) is an **opaque namespace key, not a path**: it is mapped to exactly one folder via the shared `agent_framework._filesystem._storage_key_segment` derivation, which is **injective** (except for a collision-resistant digest fallback past a length cap) — two byte-distinct values do not share a working folder, so a caller authorized for one identifier cannot reach another's memories. A multi-segment value such as `"tenants/alice"` therefore becomes a single encoded folder rather than a nested directory. The provider **fails closed** (`ValueError`) when neither a `scope` nor a `session_id` is available, because an empty working folder would be the shared store root. Applications should still canonicalize and authorize externally supplied identifiers themselves; the storage mapping is the storage-layer guarantee, not a substitute for that check.
- **Descriptions & index** - `file_memory_write` accepts an optional `description`, stored in a companion `<stem>_description.md` sidecar. After each write/delete the provider rebuilds a capped (50-entry) `memories.md` index, and `before_run` injects that index as a `user` context message so the model knows what memories exist. Sidecars and the index are internal files hidden from `file_memory_ls`/`file_memory_grep` and rejected as write targets.
- **Descriptions & index** - `file_memory_write` accepts an optional `description`, stored in a companion sidecar named after the *whole* memory file name (`notes.md` → `notes.md._description.md`), so distinct files never share a description. Names whose sidecar would exceed the 255-byte filesystem name budget — and names in the reserved `~memory-desc-` digest namespace (matched after NFKC + casefold) — use a SHA-256 digest sidecar instead, derived from the backend's canonical stored name so a case-folding store cannot scatter one description across spellings. Sidecars written by the pre-isolation format (`<stem>_description.md`) are still read as a fallback, but only when no other existing memory file shares the stem (stems compared with `casefold`); clearing or deleting a file clears its unambiguous legacy sidecar too. After each write/delete the provider rebuilds a capped (50-entry) `memories.md` index, and `before_run` injects that index as a `user` context message so the model knows what memories exist. Sidecars and the index are internal files hidden from `file_memory_ls`/`file_memory_grep` and rejected as write targets.
- **`DEFAULT_FILE_MEMORY_SOURCE_ID`** / **`DEFAULT_FILE_MEMORY_INSTRUCTIONS`** - Public defaults for the provider's source id and instruction banner.
- **Harness wiring** - `create_harness_agent` includes the `FileMemoryProvider` by default; the `FileAccessProvider` is opt-in and added only when a `file_access_store` is supplied (no implicit `{cwd}/working` store is created). Disable file memory via `disable_file_memory`; override its backing store via `file_memory_store`. When no file-memory store is supplied, the default is `FileSystemAgentFileStore` rooted at `{cwd}/agent-file-memory`. `create_harness_agent` also wires in `MessageInjectionMiddleware` by default (mirroring the .NET harness's `UseMessageInjection`); it is always on with no opt-out because it is a no-op when no messages are queued for the session.
- **Experimental-feature gating** - `create_harness_agent` itself is released (no longer `@experimental`), but a few features it can wire in remain experimental or pre-release: **background agents** (`background_agents`), **file access** (`file_access_store`), **looping** (`loop_should_continue`), and the **shell tooling** (`shell_executor`, from the pre-release `agent-framework-tools` package). Enabling any of them emits a single `ExperimentalWarning` (naming the responsible parameter). The three experimental harness providers share one `HARNESS` dedup key so the downstream experimental provider does not warn a second time; the shell tooling uses a separate dedup key (it is not a `HARNESS`-decorated feature).
Expand Down
11 changes: 10 additions & 1 deletion python/packages/core/agent_framework/_harness/_file_access.py
Original file line number Diff line number Diff line change
Expand Up @@ -1151,10 +1151,19 @@ async def write(self, path: str, content: str, *, overwrite: bool = True) -> Non
if not overwrite and key in self._files:
raise FileExistsError(f"File already exists: {path!r}")
is_new_file = key not in self._files
self._files[key] = (display, content)
if is_new_file:
self._files[key] = (display, content)
for ancestor in ancestors:
self._dir_counts[ancestor] = self._dir_counts.get(ancestor, 0) + 1
else:
# Overwriting through a differently-cased path updates the same
# file without renaming it — that is what a case-insensitive
# filesystem does — so keep the display name recorded when the
# file was created. Callers that derive stable identities from
# the stored name (such as FileMemoryProvider's digest
# sidecars) would otherwise see it flip with each spelling.
previous_display = self._files[key][0]
self._files[key] = (previous_display, content)

async def read(self, path: str) -> str | None:
"""Return the file content, or ``None`` if the file does not exist."""
Expand Down
Loading
Loading