Filesystem Memory for Coding Agents: Paths, Permissions, and Provenance
A filesystem can provide a useful interface to agent memory: records have paths, content can be inspected, and familiar read operations can retrieve context. That interface does not automatically solve freshness, permissions, concurrent edits, or the difference between a note and current source code.
Design the file contract around how the agent works. Stable paths help navigation; explicit source and version information help prevent old notes from becoming false authority.
Separate source files from derived notes
The repository remains authoritative for its current implementation. A memory file can explain why a decision was made or point to relevant modules, but it should identify the revision or source it describes.
Do not overwrite maintained project instructions with automatically extracted observations. A note that a workaround succeeded once should not become a permanent command for every future task.
Make writes recoverable and attributable
When multiple workers can update the same note, define conflict handling. A last-writer-wins policy can erase useful context without any obvious error. Consider version checks, append-only event records, or a reviewed consolidation step depending on the workload.
Record whether a change is proposed, applied locally, or merged. A later agent should not infer deployment from a file that merely describes an intended patch.
Treat paths as names, not permissions
A project directory can organize records, but access still needs enforcement by the host or service. Prevent a model-supplied path from escaping its allowed workspace. Shared and personal notes require explicit boundaries.
If a remote service presents a filesystem abstraction, verify which operations, consistency guarantees, and permission controls it actually supports. Familiar command names do not prove identical behavior to a local filesystem.
Evaluate navigation and stale-state recovery
Create a fixture with a moved source file, a corrected note, concurrent edits, and an inaccessible project. Check whether the agent follows current evidence and preserves the relevant rationale across sessions.
For OpenClaw users, the capture-versus-recall troubleshooting guide applies the same boundary checks to the documented integration.
The repository-memory guide covers freshness, and the memory architecture guide helps compare interfaces. For a managed coding workflow, follow the Supermemory Claude Code setup and test one recurring repository task rather than assuming a filesystem interface alone guarantees recall.