wuyang/agent
2
2
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document and harden project handoff

Browse Source
This commit is contained in:
wuyang
2026-07-12 14:54:03 +08:00
parent ab758e774e
commit 8e4ff3779b
17 changed files with 1030 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/06-project-status.md
+158
View File
@@ -0,0 +1,158 @@
# Project Status
last_reviewed: 2026-07-12
baseline_before_handoff: `ab758e7`
branch: `main`
remote: `https://git.k1412.top/wuyang/agent.git`
## Purpose
The repository began as a durable Agent knowledge base and now has two layers:
1. a collection layer for papers, Beijing jobs, and company Agent work;
2. an experimental knowledge interface and research layer intended to turn the collection into evidence-backed understanding.
The long-term product is not “a place to browse papers.” It should help the user retain claims, connect them into a personal model, test that model, and use it to reason about unfamiliar Agent problems.
## Current Snapshot
The deterministic index currently contains 989 items:
| Collection | Count | State |
| --- | ---: | --- |
| papers | 974 | 959 queued, 15 skimmed |
| jobs | 6 | 4 active, 2 unknown |
| industry | 9 | 8 analyzed, 1 queued |
The expanded arXiv run saw 1,506 candidates, promoted 970 high-recall candidates, and retained 536 reserve candidates. These are collection counts, not quality or reading-completion counts.
The memory topic has two intentionally different counts:
- 296 indexed items have the broad `memory` topic, including non-paper streams;
- 293 local paper items were resolved for the dedicated memory audit.
The memory research snapshot contains:
| Stage | Count |
| --- | ---: |
| paginated arXiv candidates | 516 |
| lexical title-central upper bound | 379 |
| recent-six-month title-central candidates | 292 |
| PDFs downloaded and text-located during the audit | 32 |
| papers promoted into the evidence ledger | 23 |
The strongest current conclusion is that recent progress is concentrated in better diagnosis/evaluation and task-specific execution-state memory, not a universal memory architecture. Read `research/memory/findings.md` before making memory design claims.
## Artifact Map
| Area | Source of truth | What it contains |
| --- | --- | --- |
| entry/navigation | `README.md` | human-facing repository map |
| AI continuation | `AGENTS.md` | read order, contracts, commands |
| stable concepts | `docs/00-05*.md`, `docs/99-glossary.md` | knowledge map, principles, architecture, practice, evaluation, collection |
| current state | `docs/06-project-status.md` | counts, runtime, artifact inventory |
| exploration history | `docs/07-exploration-history.md` | accepted and rejected routes |
| continuation plan | `docs/08-next-work.md` | priorities and definition of done |
| jobs | `jobs/` | Beijing-first rolling six-month JD stream |
| papers | `papers/` | paper metadata, queue, notes, corpus summary |
| industry | `industry/` | official reports, blogs, products, benchmarks |
| collection runs | `collection-runs/` | queries, scope, counts, method notes |
| collection tools | `tools/collection/` | item creation, arXiv collection, promotion, indexing, URL checks |
| research | `research/memory/` | field findings and evidence ledger |
| research data | `data/research/` | committed corpus, screening, landscape and CSV ledger |
| research tools | `tools/research/` | paginated search, abstract fetch, screening, classification, landscape build |
| experiments | `experiments/knowledge-compilation/` | failed pilot and completed field audit |
| learning prototype | `learning/agent-memory/` | preserved failed 12-paper learning module |
| web application | `web/` | Atlas, search agent, paper reader/chat, Ollama actions |
| project integrity | `tools/check_project.py` | offline structural and data checks |
`projects/` and `references/` are still mostly scaffolding. They do not yet contain substantive project or general-reference catalogs.
## Data Lineage
```text
official/web/arXiv sources
-> jobs|papers|industry/items/*.md
-> tools/collection/build_index.py
-> data/index.json + data/summary.json
-> web/app.py
-> Atlas / search / paper reading UI
```
The dedicated memory audit is separate:
```text
paginated arXiv queries + local memory-tagged papers
-> data/research/* corpus snapshots
-> model-assisted triage + deterministic statistics
-> selected full-text experiment checks
-> research/memory/evidence-ledger.md
-> research/memory/findings.md
```
Do not merge these two lines silently. The first is a broad browsing corpus; the second is an evidence audit with explicit boundaries.
## Web Application
Capabilities currently implemented:
- topic Atlas with ECharts and SVG fallback;
- routes, timeline, topic focus and paper filtering;
- desktop/mobile responsive reader mode;
- local keyword search plus an Agent search loop;
- Chinese query interpretation and English keyword expansion;
- asynchronous search activity, aggregate statistics and AI brief;
- follow-up questions on a search result;
- per-paper abstract fetch, summary, translation, deep analysis and chat;
- single-concurrency Ollama access and local caches.
Run it with:
```bash
web/manage.sh start
web/manage.sh status
```
Expected addresses:
```text
local/Tailscale: http://100.114.68.27:18080
public mapping: https://lab.k1412.top/
health: /api/health
```
At the beginning of the 2026-07-12 handoff audit, no process was listening on 18080 and the public domain returned 502. The handoff added and enabled a user-level systemd service through `web/manage.sh`; local and public health then returned 200 with 974 papers and `ollama_ready: true`. Runtime status is still external state and must always be checked live.
The live Ollama inventory checked on 2026-07-12 included `ChatGPT-5.6:Luna`, `Terra`, `Sol`, `auto`, `embed`, and `gpt-4o:latest`. The web defaults were updated from stale `light/fast/large` tags to configurable Luna/Terra/Sol tiers.
## Runtime Constraints
- Python standard library only; no package installation is required for the current web server and collection scripts.
- Ollama endpoint defaults to `http://192.168.1.10:11434`.
- One V100 32G serves all local models; AI calls are serialized.
- Do not send `num_ctx` or `keep_alive` from clients. Server-side context and residency must remain authoritative.
- `Sol` is the expensive tier and should require an explicit user action.
- The user mentioned an unlimited company GPT-5.5 data-agent API as a possible stronger offline worker, but no endpoint/authentication contract is committed. It is not currently integrated.
- The public site has no repository-managed authentication or TLS configuration; the domain mapping is external infrastructure.
- The committed systemd unit assumes the checkout path `%h/Code/agent`; edit the unit if a future checkout uses a different path.
- Full PDFs and extracted text used during the memory audit were temporary working files and are not committed. Their arXiv IDs and claim boundaries are preserved in `research/memory/evidence-ledger.md` so they can be fetched again.
- `web/cache/` contents, including arXiv responses, AI outputs, service environment and logs, are intentionally not committed.
## Validation
Offline validation:
```bash
python3 tools/check_project.py
git diff --check
```
Live validation:
```bash
web/manage.sh status
curl -fsS http://100.114.68.27:18080/api/health | jq
curl -fsS https://lab.k1412.top/api/health | jq
```
The health payload reports app/assets versions, paper count, available/default models, and missing default model tags.
docs/07-exploration-history.md
+159
View File
@@ -0,0 +1,159 @@
# Exploration History
last_reviewed: 2026-07-12
This is the decision history, including failed routes. Preserve it so future work does not rediscover the same lessons.
## 1. Repository and Content Streams
On 2026-07-08 the workspace was initialized as a long-lived Agent knowledge base, not a one-off report.
The first structure included stable knowledge, projects, experiments, references, and templates. It was then expanded into three first-class collection streams:
- `jobs/`: Beijing-focused Agent/LLM roles over a rolling six-month window;
- `papers/`: research evidence and reading queue;
- `industry/`: large-company reports, blogs, products, repositories, and benchmarks.
Decision retained: papers, jobs, and industry must not be mixed because they answer different questions. Their common organization layer is metadata/index/search, not a deep directory taxonomy.
Relevant commits: `47cea9d`, `1b6cc1f`, `36c2499`.
## 2. First Collection and Expanded Corpus
The first sweep created 21 items and the source/schema workflow. The expanded arXiv sweep then recalled 1,506 candidates and promoted 970 high-relevance candidates, bringing the paper corpus to 974.
What worked:
- source registries and explicit source quality;
- keeping candidate and promoted manifests;
- generated frontmatter plus a deterministic index;
- preserving `queued` as a truthful unread state.
What did not work:
- treating the resulting count as understanding;
- assuming auto tags were a stable taxonomy;
- using non-paginated/latest-only query results to infer historical trends.
Relevant artifacts: `collection-runs/`, `papers/corpus-summary-2026-07-08.md`, `data/arxiv-agent-*.json`.
Relevant commits: `1cbc98e`, `391b3a4`.
## 3. Paper Browser to Knowledge Atlas
The first frontend exposed search, filtering, paper preview, abstract fetch, translation, summary, and deep analysis. It evolved into a knowledge Atlas with topic nodes, co-occurrence, timelines, routes, desktop/mobile layouts, and an ECharts graph.
Further iterations fixed:
- cache busting and stale deployment confusion;
- an oversized Atlas payload;
- desktop scrolling and reader focus;
- mobile map centering;
- interactive graph visuals;
- app version visibility.
This produced a usable corpus browser, but the user later rated its practical learning value at effectively 0/100. The reason was not mainly visual quality: exploration was stateless, and nothing helped the user retain, compress, challenge, or apply knowledge.
Decision retained: the Atlas may remain an orientation surface, but it must not be treated as the product or as evidence of learning.
Relevant commits: `e783a7d` through `15b5cec`.
## 4. Search Agent and Per-Paper AI
Search was upgraded from keyword matching to a compact Agent loop:
```text
interpret query -> expand Chinese/English terms -> retrieve locally
-> aggregate dates/topics/trends -> generate brief -> allow follow-up
```
The UI initially exposed every fixed pipeline step. That looked mechanical, so it was simplified into one active status row with a changing task summary. Paper reading also gained multi-turn chat.
What worked:
- AI-assisted query interpretation and bilingual expansion;
- progressive activity updates instead of a blocking spinner;
- contextual follow-up over a bounded result set;
- serialized model use and caching.
What remained insufficient:
- AI actions were still centered on individual papers or a single search;
- the system did not maintain claims, contradictions, the user's evolving model, or review state;
- a generated brief disappeared into another stateless browsing session.
Decision retained: future AI should operate at the claim/evidence/model level, not merely summarize or translate documents.
Relevant commits: `894c914`, `4892e7a`.
## 5. Ollama Integration Lessons
The application originally sent client-side context/residency parameters. The user identified that a `num_ctx` mismatch could restart a model and clear residency, and that `keep_alive` behavior could unload it.
The fix was to let the Ollama server own both settings. The application now only sends generation options such as temperature and output length, serializes calls, and caches results.
On 2026-07-12 the live model inventory no longer contained the old `light/fast/large` tags used by the web app. The defaults were changed to configurable tiers backed by the currently available Luna/Terra/Sol tags, and health now reports model mismatches.
Decision retained: always verify `/api/tags`; never infer deployed model aliases from old documentation.
Relevant commits: `47c301c`, `ac6e0e0`, and the 2026-07-12 handoff update.
## 6. Learning-System Reframing
The user clarified the real objective with three levels:
1. complete memory of important knowledge;
2. compression into a coherent network/system;
3. abstraction that can explain why approaches exist and generate recommendations for new goals.
The desired system is a scaffold from raw papers to internalized judgment. The user expects Codex or another strong AI to be an active research partner, not merely an orchestrator for small local models.
This reframing invalidated “paper site” as the primary product definition.
## 7. Failed 12-Paper Learning Pilot
The first response to the reframing compiled 12 Agent Memory papers into a map, chapter, evidence matrix, active recall, and machine-readable module.
The user rejected it because:
- 12 papers were too few for a field-level trend;
- it felt like a lecture rather than joint research;
- it did not answer what 200+ papers were doing;
- it did not compare current failures with six months earlier;
- it did not establish whether architecture gains were attributable.
The experiment is explicitly `failed` in `experiments/knowledge-compilation/2026-07-10-agent-memory-pilot.md`. Its artifacts remain under `learning/agent-memory/` only as historical material.
Decision retained: a polished educational package is not valuable until the underlying field audit and the user's own learning interaction are validated.
Relevant commit: `36c631e`.
## 8. Agent Memory Field Audit
The failed pilot was replaced with a broader research audit:
- five paginated arXiv queries;
- 516 unique abstract-level candidates;
- complete local screening as triage;
- exact recent/prior six-month windows;
- 32 downloaded/text-located papers;
- 23 papers in an evidence ledger with explicit non-extrapolation boundaries.
The most useful findings were negative or diagnostic:
- retrieval quality often matters more than elaborate write structures for static QA;
- model and embedding choices can reverse architecture conclusions;
- update/forgetting and automatic writing remain unsolved;
- execution-state memory is the clearest task-specific capability direction;
- memory can interfere with other Agent components;
- cost and no-memory baselines are mandatory.
This audit is the current research baseline. Read `research/memory/findings.md` and `research/memory/evidence-ledger.md` rather than the old learning module.
Relevant commit: `ab758e7`.
## 9. Current Position
The repository now has a strong collection substrate, a functioning exploration prototype, and one evidence-led field audit. It does not yet have the stateful personal learning/internalization layer that motivated the project.
The next meaningful experiment is not another graph redesign or another bulk paper sweep. It is one end-to-end learning path that records a user's claims, evidence judgments, contradictions, applications, and later recall, using the memory audit as its first evidence base.
docs/08-next-work.md
+167
View File
@@ -0,0 +1,167 @@
# Next Work
last_reviewed: 2026-07-12
## P0: Build One Stateful Learning Path
Use Agent Memory as the first vertical slice, but do not reuse the failed 45-minute lecture format.
The unit of interaction should be a claim, not a paper. A minimal claim object needs:
```text
question
claim
supporting evidence
counterevidence
confidence
scope / failure boundary
prerequisites
related claims
user judgment
last reviewed / next review
```
The first path should contain a small number of consequential claims from the existing audit, for example:
- strong retrieval can dominate write complexity on static QA;
- current-value maintenance is distinct from retrieval;
- execution-state memory is different from historical recall;
- automatic experience promotion requires evidence and rollback;
- memory can have negative marginal value inside an Agent scaffold.
The interaction should progressively reveal:
```text
problem -> current hypothesis -> evidence -> conflicting evidence
-> user judgment -> application to a new design -> delayed recall
```
Persist the user's state. Merely rendering these sections is not enough.
### P0 Data Work
Define a versioned, inspectable local schema before adding a database. Suggested initial files:
```text
data/learning/claims.json
data/learning/user-model.json
data/learning/reviews.jsonl
```
Requirements:
- every claim links back to evidence-ledger entries;
- user notes and AI synthesis remain distinguishable;
- claim updates preserve history;
- confidence changes record a reason;
- review records are append-only;
- no generated summary can silently replace source evidence.
### P0 AI Roles
Use AI above the per-paper level:
- evidence auditor: check whether a claim is actually supported;
- contradiction finder: surface papers that challenge the current model;
- synthesis maintainer: update the claim network when evidence changes;
- research partner: help the user reason through an unfamiliar target;
- review generator: create recall/application prompts from validated claims.
Use Luna for cheap classification, Terra for retrieval briefs and bounded dialogue, and Sol only for explicit synthesis/critique. The user also has a company GPT-5.5 data-agent API with effectively unlimited tokens, but integration must wait until its endpoint, auth, rate behavior, and data policy are documented.
### P0 Validation
Do not judge success by page completion or time spent. Validate whether the user can:
1. explain five claims without paper names;
2. identify the evidence boundary of each claim;
3. diagnose a new Agent memory design;
4. predict when memory will hurt;
5. recover the model after 1, 3, and 7 days;
6. change a belief when presented with counterevidence.
## P1: Connect Research to the Frontend
The current Atlas/search/reader can remain, but it should feed the stateful path:
- selecting a topic opens its unresolved questions and claims, not only a paper list;
- selecting a paper shows which claims it supports or challenges;
- search results can be promoted into an evidence review queue;
- paper chat can create a candidate claim, never an automatically accepted fact;
- the primary desktop focus should shift to the active research/learning task;
- mobile should preserve the same conceptual flow with fewer simultaneous panes.
Avoid another navigation-heavy redesign before the data and learning loop exist.
## P1: Continue Collection Selectively
Current gaps:
- only 6 JD items, last checked 2026-07-08;
- only 9 industry items;
- 959 of 974 paper items are still queued;
- paper source approval and automated collection policy need an explicit user decision;
- the corpus is heavily biased toward May-July 2026 and broad arXiv query terms.
Next collection work should be question-driven:
- refresh Beijing DeepSeek/Tencent/ByteDance/Alibaba/Baidu roles and record changes;
- add official company material that explains memory, evaluation, coding agents, or computer use;
- deepen only papers that challenge or extend current claims;
- do not add another thousand papers without a processing and evidence plan.
After any item changes:
```bash
python3 tools/collection/build_index.py
python3 tools/check_project.py
```
## P2: Research Refresh Protocol
When refreshing the memory audit or starting another topic:
1. define exact date windows and approved sources;
2. save the broad candidate snapshot;
3. separate deterministic filters from model triage;
4. identify comparable benchmarks and controlled studies;
5. read experiments, ablations, costs, and limitations in full text;
6. update an evidence ledger before writing conclusions;
7. preserve negative results and failed hypotheses;
8. record the run under `experiments/` and update project status.
Do not compare raw scores across papers unless model, embedding, prompt, visible information, and budget are controlled.
## P2: Operations
Still missing:
- public-domain deployment documentation outside this repository;
- authentication/authorization for a public or multi-user site;
- automated backup for future personal learning state;
- CI that runs `tools/check_project.py` on push;
- tests for web API behavior and frontend flows.
The repository now has an enabled user-level systemd service managed through `web/manage.sh`. It restarts on failure and survives user sessions because linger is enabled on the current host, but it is not a complete production deployment: proxy/TLS/auth configuration remains external.
## Explicit Non-Goals
- Do not make the graph more decorative as the next milestone.
- Do not present 974 queued papers as knowledge already learned.
- Do not revive the 12-paper lecture as the primary path.
- Do not use per-paper summary/translation as the main AI value proposition.
- Do not let AI write durable memory solely because a statement repeats in traces.
- Do not hide model, embedding, context, or cost changes inside an architecture comparison.
## First Continuation Task
The best next task for another AI is:
1. read the memory findings and evidence ledger;
2. define the claim/user-state/review schemas;
3. compile 5-8 audited claims into a stateful local dataset;
4. implement one progressive learning/research view;
5. run it with the user and record what changes in their understanding;
6. keep or discard the interaction model based on that evidence.
That is the shortest path from the current corpus browser toward the actual goal.