Filesystem Agent Memory Research

How should persistent files help an unfamiliar agent recover the context it needs to continue work accurately?

This public repository has two parts. One is a source-grounded review of agent memory, retrieval, personal information management (PIM), digital preservation, biological memory and human learning practices. The other is a set of original executed experiments. The work prioritizes preserving important details, resolving changing state and succeeding after a fresh start. It studies PARA alongside other organizational approaches and does not assume that any folder taxonomy is optimal. It is an AI-assisted structured scoping review. It is not an exhaustive systematic review, a peer-reviewed publication or a validated benchmark.

Start with the current report. It is the living synthesis of conclusions, evidence boundaries, a minimal design to test and open questions.

This README and the current report were refreshed October 24, 2026 UTC. The last executed experiments are dated October 16, 2026 UTC. No new experiment was conducted for this documentation refresh, and it reports no new source search or review. Dated study reports remain linked as archives. Their frozen outcomes are not replaced or regraded.

Strongest bounded conclusions

The project separates four kinds of failure: preservation, discovery, interpretation and action. Results are reported on three separate levels:

• Deterministic source exposure: what evidence reaches a packet.
• Reader performance: what a model answers from that packet.
• Actual task actions: what the agent does.

The counts below are repeated measurements over shared engineered workloads, and they come from different studies. Do not pool them into an independent sample size or a population accuracy estimate.

• No universal winner. Neither the reviewed literature nor these experiments establish a universally best taxonomy, retriever or model. They also do not justify a production migration or deletion. The direction worth testing has three parts: recoverable source evidence, a maintained current-state view, and simple navigation that expands back to sources.
• Reversible demotion preserves far more than age-based removal in this workload. The October 16 pruning study ran 64,512 deterministic query-arm trials: 1,024 repeated queries, 32 fictional growing worlds, 32 epochs and 63 arms. Its eight workload overlays share one authored backbone. Success requires the correct value plus every gold-required original and qualifier.
  • Global retain-all succeeds on 1,008/1,024.
  • LRU/LFU reach 1,004 without an archive, losing four dormant prerequisites. With archive recovery they reach 1,008.
  • An eight-epoch TTL reaches 380 without an archive and 988 with recovery.
  • Project-only retain-all reaches 760, versus 1,008 for global or linked routing, because it often misses a cross-project qualifier.
  • Retain-all quality does not decline between the two tested distractor densities.
  • The dependency-guard contrast is unactivated in this bank.
• Smaller active sets cut scoped work, not total storage. Under global retrieval, archive-off LRU/LFU reduce mean active original bytes by 51.57% at the final epoch. They reduce scoped candidate examinations by 31.95% across checkpoints. These are counters, not measured tokens or latency. With an archive, total retained original storage does not shrink.
• The reader follow-up separates available evidence from current-state agreement. The follow-up collected 48 fixed outputs in eight fresh contexts.
  • All 35 packets with complete gold support yield matching values and every required citation.
  • Ten abstentions and three stale answers occur where evidence is missing.
  • Zero outside-packet citations did not prove current-source coverage.
  • Inference is limited by structured ASSERT packets, repeated values and task/context confounding.
  • Autonomous PARA discovery was not validated.
• Wider context exposes more governing text, but not universally. The October 15 context experiment built 6,480 packets for 216 known queries from the October 13 bank. These are repeated packings, not new independent cases.
  • At 8 KiB, complete authored-span exposure rises from 60/216 to 215/216 under body BM25 and to 216/216 under entity RRF, using radius-8 windows or whole bodies.
  • No reader answered these packets.
  • At 4 KiB, whole bodies gain 144 and 143 queries but also lose 2 and 5, respectively.
• Correct values are not complete proof. The state study ran 1,152 deterministic trials: twelve arms × 96 parameterizations of one authored topology.
  • With shuffled navigation edges, the ledger/facet arm still returns both current values in 96/96 cases but complete proof in 0/96.
  • Proof gating prevents false grants, but every incomplete arm withholds all 48 useful true grants.
  • Only the complete-proof arm safely grants all 48.
• Earlier strict scores are conjunctions, not factual accuracy. Strict completion scores in the October 9, 11 and 13 studies require several conditions at once. Separate blinded LLM reviews found source-supported requested values in 66/123 October 11 artifacts and in 22/24 responses per October 13 direct-reader arm. These reviews are distinct measures, not human validation or regrading. In the October 13 closure-passage / 8 KiB / 144-record cell, all 21 rankers tied at 60/216 complete-span exposure despite 216/216 original-ID coverage. That result motivated the October 15 context lane.

Reading map

Document	Use
Current report	Living synthesis; read first
Pruning through extended use	October 16 deterministic study; six main scientific figure pairs
Fresh readers after pruning	October 16 reader follow-up; one reader figure pair (seven pruning figure pairs total)
October 15 mechanism sprint	Context, state/proof and onboarding lanes; six scientific figure pairs
Fresh-agent evaluation protocol	Tests retention, discovery, interpretation and continuation separately

Topic reviews

Review	Covers
Agent memory	Evidence, current state, temporal updates, handoffs
Retrieval and context	Search, long context, sufficiency, attribution
Organization and retention	Human PIM, folders/tags/facets, PARA, stable IDs, preservation
Pruning and longitudinal memory	Cache policies, compaction, forgetting, reversible demotion
Recent evidence	2025–2026 studies and engineering reports
Biological memory	Binding, consolidation, replay, updating, forgetting
Human memory practices	Retrieval practice, spacing, cues, external reminders
Applying human and biological ideas	Transfer limits and falsifiable experiments
Filing hypotheses	Eight interventions with matched controls
Methodology	Selection, verification, evidence categories

Sources. The annotated bibliography indexes the machine-readable catalogs, including the historical 125-record bibliography. The pruning source catalog is a separate, scoped October 16 extension that includes revisited works. Catalog entries are not summed into a unique-paper count.

Dated archives (frozen)

• October 16: pruning report, reader follow-up, execution record, acceptance record
• October 15: sprint overview, context expansion, state and authorization, onboarding check
• October 13: primary report and 26 figure pairs, execution and numeric audit, blinded review of all 192 artifacts. Supplements, recovery records and unexecuted protocols are in the study directory.
• October 11: expanded report and 15 figure pairs, execution audit, blinded review, protocol
• October 9: pilot report and 12 figures, interactive viewer (download to interact), independent audit

Verify and reuse

You need Python 3.10 or later. Repository checks use the standard library. Figures and the October 11 scoring runtime need additional packages, which are documented in their reports. Run these from the repository root:

python -B scripts/check_repository.py
python -B evaluation/pruning-2026-10-16/check_release.py
python -B scripts/check_maintenance_replay.py --self-check

1. Root check. Covers catalog structure, citation mappings, local links, publication hygiene and fixture references.
2. Pruning release check. A read-only check of the October 16 extension's files and navigation.
3. Maintenance wrapper. Runs the frozen pilot runner and fixture in a temporary copy. It compares the output byte for byte with the retained result and confirms the originals are unchanged. Use it instead of the pilot's direct replay --self-check, which rewrites the retained results.

These are bounded checks. Passing them does not validate scientific claims, prove privacy or establish that a study completed correctly. Historical audit receipts describe their release snapshots; the October 13 baseline audit also pins the old synthesis. Use the documentation checks above for this living report refresh, without changing those historical audits. For reproduction, follow each dated report. Some generation and rendering routes write files and should target new destinations. Read the protocol and the fictional fixture before staging trials.

Limits

• The workloads are engineered and modest in scale. They use supplied metadata, aliases and links, and they share backbones or topologies. They are not natural vaults.
• The pruning and state results rely on deterministic selection and reading. LLM reviews are not human validation.
• Pruning's active-source and candidate-work reductions do not establish token, end-to-end latency or filesystem-speed benefits.
• The synthesis conclusions are not pooled causal estimates.
• Priority next tests:
  • independently authored corpora with frozen policies
  • broader unfamiliar-reader trials
  • expiry-aware compaction
  • cold-store byte reservations
  • autonomous discovery

Scope, licensing and contribution

Public primary sources are linked rather than mirrored. The original prose, examples and scripts use the MIT license; third-party works retain their own rights. See privacy, methodology and contribution guidance. Corrections and extensions are welcome, especially matched experiments, negative results and tests with unfamiliar readers and changing evidence.