# CUBE notes ↔ model integration: `cube-notes-agent`

The CUBELinux-2 note/message-save-path is a durable, searchable log that a small
local LLM reads, reviews, and writes back to — a closed loop that is **grounded
in CUBE** (the model never invents findings) and **incremental** (each run reviews
only what has not been seen).

## The notes system (`cubesys::notes`)
- WordFlags-tagged **CZYX** note log. Each note has `doc_type = note:<category>`
  (categories like `finding`, `action`, `checkpoint`, `resume`, `task`, …) and an
  optional **project** association via `linked_records`.
- `cube note add|list|search|show`; `cube project list|show|resume|context`.
- `cube note tag <coord> <cat>` reclassifies a note in place (Puts are durable;
  `delete_raw` is not — the checkpoint/delta only records Puts of surviving keys,
  so a deleted key resurrects from the base snapshot on reload).
- Durable `ConcurrentStore` (WAL + delta + checkpoint). Short-lived processes must
  `store.checkpoint()` before exit or buffered writes are lost.

## Model ↔ CUBE
- `cube-notes-mcp.py` (stdio MCP server) exposes `mcp__cubenotes__note_*` /
  `project_*` tools to the DeepSeek Harness. The harness registers the mcp-client at
  the **bundle** layer (`inject: [tools]`); profile-layer rows can't inject the tools
  service, so the plugin silently never mounts — the bundle registration was the fix
  that made `mcp__cubenotes__note_*` live.
- `tools/cube-notes-agent.py` (headless, cron-driven, no control panel) treats CUBE as
  the agent's memory:
  - every action is written as a note (`category=action`) so a run can be replayed;
  - a review run reads **only uncovered** findings (`category=finding`), asks the model
    to rank them, then writes a grounded report and marks them covered with a
    `checkpoint` note — true incremental, non-destructive review;
  - the report is composed in Python from the finding notes **verbatim**, with a
    deterministic severity (HIGH/MEDIUM/LOW) and priority order, so no content is
    invented. Report ⇒ a review `.txt` (`/root/workspace/cube-agent/report.txt`).

## Success: tracing errors from prior run data saved in CUBE
- The findings/action trace already stored in CUBE (from prior runs) is the source of
  truth. The broad scan surfaced **7 un-categorized logs** that had been logged but
  never tagged `finding`: `GIT-SHALLOW-CLONE`, `POSTFIX-TLS-CERTS`,
  `SELINUX-RESTORECON`, `DSH-WEB-EADDRINUSE`, `CONCURRENT-STORE-CHECKPOINT`,
  `MCP-BUNDLE-LAYER`, `CUBES-TWO-TREES`. See `git log` entry `bd3e3c0`.
- Coverage is precise: the report marks exactly the findings it reviewed, so the next
  run reports only new ones. The notes store is also the harness GUI's CUBE surface
  (`mcp-cubenotes note_list`), so everything the agent writes is visible and reviewable.

## Usage
```
python3 tools/cube-notes-agent.py --max-turns 6 --report /path/report.txt
```
Runs single-instance via `flock`; a cron schedule (e.g. `0 6,18 * * *`) drives it.