agent/AGENTS.md

AI Continuation Guide

This file is the entrypoint for any AI or engineer continuing the repository.

Start Here

Run these commands before changing anything:

git status --short --branch
git log -5 --oneline --decorate
python3 tools/check_project.py
sed -n '1,260p' docs/06-project-status.md
sed -n '1,260p' docs/07-exploration-history.md
sed -n '1,260p' docs/08-next-work.md

The active branch and remote are normally:

branch: main
remote: https://git.k1412.top/wuyang/agent.git

Do not assume the public web service is running just because the repository is healthy. Check it separately:

web/manage.sh status
curl -fsS https://lab.k1412.top/api/health | jq

Actual Goal

This is not merely a paper browser. The user wants a scaffold that turns a large raw corpus into personal, reusable cognition:

1. remember important knowledge;
2. compress it into a coherent system;
3. use that system to explain causes, compare approaches, answer new questions, and propose designs.

The current Atlas is a corpus exploration prototype, not a validated solution to this goal. The user rated its practical learning value at effectively zero because browsing left no durable learning state. Do not spend the next iteration polishing the graph without addressing this gap.

Truth Hierarchy

Treat repository artifacts according to their evidence level:

1. research/*/findings.md and evidence-ledger.md: current evidence-backed conclusions.
2. experiments/*: method, failures, and validation boundaries.
3. docs/: stable system-level knowledge, but verify dates and sources before extending it.
4. papers/items/*.md with status: skimmed: partially reviewed.
5. papers/items/*.md with status: queued: collection records only, not understood papers.
6. Auto tags and model screening outputs: high-recall triage, never final truth.

The old learning/agent-memory/ module is retained as a failed experiment. It is not the current synthesis. The Agent evaluation design under research/evaluation/ is an implementation contract, not a completed benchmark. Its task contracts explicitly mark which runners do not exist yet. evaluation-site/ is a presentation layer for that contract. It must not introduce stronger claims than the research artifact or display simulation values as real benchmark results.

Repository Contracts

• Keep jobs, papers, and industry practice as separate first-class streams.
• Use metadata and indexes for cross-cutting organization; do not make deep directories the primary UX.
• Preserve original sources and raw traces. A summary must not overwrite evidence.
• Distinguish collection, screening, full-text evidence, synthesis, and user learning state.
• Run python3 tools/collection/build_index.py after changing item frontmatter.
• Run python3 tools/check_project.py and git diff --check before committing.
• Use python3, not python, in this environment.
• Keep generated cache and PID/log files under web/cache/; they are intentionally ignored.
• Never commit credentials. Git authentication is configured outside the repository.

Ollama Contract

Default endpoint:

http://192.168.1.10:11434

Current model tiers are configurable with:

OLLAMA_MODEL_LIGHT=ChatGPT-5.6:Luna
OLLAMA_MODEL_FAST=ChatGPT-5.6:Terra
OLLAMA_MODEL_LARGE=ChatGPT-5.6:Sol

The application serializes Ollama calls because all models share one V100 32G GPU. Application requests must not send num_ctx or keep_alive; the Ollama server owns context size and residency. Expensive Sol actions should remain explicit, not automatic.

Common Commands

# Rebuild the main index
python3 tools/collection/build_index.py

# Validate repository integrity
python3 tools/check_project.py

# Start or inspect the web service
web/manage.sh start
web/manage.sh status
web/manage.sh logs

# Research pipeline help
python3 tools/research/search_arxiv_memory.py --help
python3 tools/research/screen_memory_corpus.py --help
python3 tools/research/build_memory_landscape.py --help

# Collection fallback when the arXiv export API is unavailable
python3 tools/collection/collect_arxiv.py --backend search-html --help

# Aggregate Agent evaluation result JSONL
python3 tools/evaluation/score_agent_runs.py --help

# Preview the static Agent evaluation report
python3 -m http.server 4173 --directory evaluation-site

Read the scripts before rerunning network or model-heavy research jobs. The committed research data is the reproducible snapshot; a refresh changes the time boundary and may be expensive.

Before Handoff

After meaningful work, update all affected layers:

• artifact or code;
• generated index/data if applicable;
• experiment record for the method and result;
• docs/06-project-status.md for current facts;
• docs/07-exploration-history.md for a new major decision or failed route;
• docs/08-next-work.md for changed priorities.

Commit with a narrow message and push main unless the user requests another branch.