Proposal: Introduce a Project-Level Long-Term Memory File and a Guidance Agent Mechanism

[wangyunjeff]

Summary

I propose introducing a more stable long-term memory mechanism for the project:

• a dedicated project-level Markdown file to preserve important experience, judgments, and directional conclusions
• a Guidance Agent responsible for maintaining that memory and helping execution-oriented Agents stay aligned

The core idea is simple: important project knowledge should not remain trapped inside temporary sessions.

Problem

When an Agent re-enters a project, it is not guaranteed to systematically review result.tsv. As a result, previously validated approaches, failed attempts, and key judgments may not be reliably carried forward.

This is manageable in short tasks, but becomes a real problem in long-running projects. As context grows, the model is more easily distracted by large amounts of historical information, which hurts:

• cross-session continuity
• judgment stability
• reuse of prior experience
• creativity and solution quality

In practice, execution can easily fall into a local optimum.

A useful analogy is neural network training: once optimization gets stuck in a local optimum, it may keep making small improvements along the current direction while missing a better path entirely. The same thing can happen here — an execution-oriented Agent may keep refining a narrow line of thought instead of stepping back and exploring a better alternative.

Why a Guidance Agent

This is why memory alone is not enough.

There should also be an Agent specifically responsible for reading, synthesizing, judging, and guiding. Its role is not just to store past conclusions, but to help execution Agents break out of local optima.

A Guidance Agent can review and integrate a large volume of reference material more effectively. These references may come from:

• materials explicitly provided by the user
• external sources discovered through the Agent's own search and discovery capabilities

Instead of passing all raw reference material directly to the execution Agent, the Guidance Agent can first filter, organize, and abstract it, then distill the most useful and reusable insights into the project-level memory file.

This creates a cleaner separation between:

• broad reading and synthesis
• concrete execution and implementation

More importantly, it gives the system a mechanism for reframing the problem, introducing alternative ideas, and guiding the execution Agent toward a better direction when it starts over-optimizing locally.

Proposal

I propose establishing a project-level long-term memory file, continuously maintained by a Guidance Agent, and using it as the primary entry point for execution-oriented Agents when they re-enter the project.

The purpose of this mechanism is not to add more context. It is to extract the most important, reusable, and inheritable knowledge from temporary conversations and scattered references, and turn it into stable project memory.

The responsibilities can be separated as follows:

• Guidance Agent: reviews references, synthesizes experience, organizes judgments, reframes problems, and provides direction
• Execution Agent: carries out concrete tasks and implementation work

[dan-y]

Agreed, ran an overnight session and my agent found the same warmdown improvement already reported in Discussion#43. Only realized after reading it, might happen to others as well. Guidance agent might be an overkill for this minimalistic repo. I'd propose:

1. Merge best config back to master, like was done with nanochat (karpathy/nanochat@6ed7d1d).
   So new runs would start from a stronger baseline and explore unknown instead of re-finding batch halving and depth 9.
2. A history of failed experiments, a simple discarded.md would let agent not repeat what's already been tried.