NeuriCo Context and Working-Memory Improvements

[Yashtik]

NeuriCo Context and Working-Memory Improvements

Contribution toward #51 — Context management and working memory.

Long research runs are difficult for AI agents. As the conversation grows, an agent can forget the original research goal, lose track of decisions made earlier, or start creating files in the wrong folder.

This contribution adds three lightweight safeguards to help NeuriCo’s research agents stay organised during long runs.

1. Keeping the research goal visible

Each project’s STATE.md now includes a NeuriCo-controlled Research Contract containing the original:

• research title and hypothesis
• constraints
• success criteria
• expected outputs

The agent is told to treat this contract as its north star throughout the run. If experimental evidence contradicts the hypothesis, it should report that honestly rather than trying to prove the hypothesis.

STATE.md also gives stage notes a consistent structure:

• Completed
• Key decisions and reasons
• Evidence/files
• Unresolved issues
• Next steps

This makes handoffs between major pipeline stages clearer and reduces vague or incomplete progress notes.

2. Checking the agent’s working directory

During an experiment, the agent may temporarily enter folders such as:

code/baseline-model/

That is normal. The problem occurs when it forgets to return to the project root before beginning the next phase. New files may then be saved in unexpected locations.

A new command, neurico-check-dir, checks the agent’s actual shell directory and classifies it as:

• workspace root
• nested inside the workspace
• outside the workspace

At every phase boundary, the agent is instructed to run the checker. If it is nested or outside, it must return to the workspace root, rerun the checker, and continue only after receiving exit code 0.

Checks are recorded and summarized in STATE.md.

This is prompt-enforced rather than a hard programmatic gate: the command objectively checks the directory when invoked, but the agent could theoretically skip it.

3. Adding phase-to-phase handoffs

The Experiment Runner completes six phases in one continuous session:

Planning → Setup → Implementation → Experiments → Analysis → Documentation

To prevent earlier decisions from getting buried, the agent now writes one concise handoff file after each phase:

phase_handoffs/
├── 01_planning.md
├── 02_setup.md
├── 03_implementation.md
├── 04_experiments.md
├── 05_analysis.md
└── 06_documentation.md

Before starting the next phase, the agent rereads the Research Contract and the immediately previous handoff.

Each handoff records completed work, decisions, evidence, unresolved issues, and next steps. Important unresolved context is carried forward, while irrelevant details can be dropped.

Together, these changes help the agent remember what it is trying to accomplish, where it should be working, and what happened during the previous phase.

Test plan

• Full pytest suite passed locally
• Confirm neurico-check-dir is available after install
• Spot-check Experiment Runner prompt includes Research Contract guidance, directory-check block, and phase-handoff block
• Spot-check a domain override still receives those blocks via prepend fallback
• Confirm Resource Finder prompt does not receive the six-phase handoff block