Skip to content

✨ knowledge: review flow and never-prime for CLI auto-memory drafts, legacy drain - #17126

Closed
Karibhou wants to merge 1 commit into
hivecommons:v5from
Karibhou:feat/cli-memory-drain-phase3
Closed

Karibhou wants to merge 1 commit into
hivecommons:v5from
Karibhou:feat/cli-memory-drain-phase3

Conversation

@Karibhou

@Karibhou Karibhou commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Closes #17058

Phase 3 of #17033. This builds on the manager-side drain from #17086, which is already on v5. That PR shipped the tag cli-memory (written both as a tag and as source: cli-memory), not auto-memory. It also shipped the config key drain_to_knowledge, not drain. This PR uses the shipped names and records the difference in a "Phase 3 as shipped" section of the design doc.

What

Drained drafts never reach an agent. A drained draft is any fact carrying the cli-memory tag or source: cli-memory (knowledge.IsAutoMemory) whose state is draft. Settings that let other drafts through do not let it through:

Path Before After
Kick primer / knowledge advisor (FilterByLifecycleFor) primed if include_states (primer or agent_scopes) admitted draft never primed
?agent= TOC, entry and effective reads listed if the request or agent scope admitted draft hidden; the effective view reports reason lifecycle
Public MCP approved only unchanged (already approved only)
AutoPromoteCandidates eligible if verified and high confidence pages tagged cli-memory are never candidates
Operator reads (/api/knowledge/search, TOC without ?agent=) listed with include_states=draft unchanged, so drafts can still be reviewed

Review flow. The drain writes its entries into bead-synth-wiki, which PUT /api/knowledge/entry/{id}/state used to refuse outright. That meant no drained draft could ever be approved. The state API now accepts entries in that vault whose frontmatter says source: cli-memory. This is safe because the drain never rewrites an existing entry. Synthesizer entries in the same vault are still refused.

The dashboard knowledge view has a new 🧠 Auto-memory drafts filter in its sources list. It shows each draft with its agent: tags, and an owner gets:

  • Approve: sets the entry to approved.
  • Discard: sets it to deprecated rather than deleting it. The drain dedupes by memhash across all states, so a discarded fact is never drafted again.

Both actions ask for confirmation, go through the existing state API and are audited.

Legacy drain. hivectl knowledge drain-memory --legacy [--truncate] calls a new endpoint, POST /api/knowledge/cli-memory/drain-legacy, which is owner-only and audited as knowledge_drain_legacy_memory.

Docs:

  • New "Auto-memory drafts" section in knowledge-lifecycle.md.
  • Operator reference (runtime-and-quota.md): how drained drafts are excluded and reviewed, and how to run the legacy drain.
  • hivectl.md, API reference and OpenAPI updated for the new command and endpoint.
  • Design index status changed to partly shipped; "Phase 3 as shipped" section added to the design doc.
  • The "known gaps" entry in agent-knowledge-and-memory.md updated.

Inserting the new route in api.go shifted line numbers, so check-docs-citations.py --fix updated 105 route citations, each by one line.

Tests

Not run locally, per AGENTS.md; CI decides. Only gofmt -l on changed files and make dashboard-gen-check were run. I ran both node UI scripts directly against the regenerated index.html, and both passed.

  • Acceptance: scheduler/kick_priming_auto_memory_test.go runs the real drainer and checks the drained fact against approved-only, draft-admitting and all scopes. It does this both with the default primer and with a primer whose include_states admits drafts. The draft is never in the kick, while an approved control fact is. After KnowledgeAPI.SetEntryState(..., approved) on the bead-synth-wiki vault, it is primed for every agent and has no (draft) marker.
  • knowledge/auto_memory_test.go:
    • Operator and kick filters, and agent and operator TOC scopes.
    • A drained entry in the reserved vault can be approved; a synthesizer entry there still returns ErrEntryNotWritable.
  • knowledge/promote_test.go: a verified, 0.99-confidence page tagged cli-memory is not an auto-promote candidate.
  • dashboard/api_knowledge_cli_memory_test.go:
    • Agent and operator TOC, entry, search and effective reads.
    • After approval through PUT /api/knowledge/entry/{id}/state, the entry shows up in the agent TOC.
    • Legacy drain: 409 without the vault, a draft with agent:shared and repo:, files untouched without truncate, then truncate, audit entries, and 400 on a bad body.
    • The new route is added to the owner-only deny table.
  • dashboard/knowledge_auto_memory_ui_test.go (node): filter URL and draft-only listing, agent tags, Approve and Discard send the PUT with approved / deprecated, a cancelled confirm sends nothing, no buttons for non-owners or for non-drained facts.
  • climemory/legacy_test.go: source discovery (missing tree, unreadable tree, symlinks skipped); truncation only empties fully stored files, and a failure leaves every file alone.
  • hivectl/commands/knowledge_more_test.go: --legacy is required, and --truncate is forwarded.

Overlap with #17123

#17123 (finishing phase 1, also mine) changes the same status line in src/docs/design/README.md and the paragraph just before my addition in runtime-and-quota.md. Whichever merges second needs a small rebase. The code does not overlap: this PR adds climemory/legacy.go and does not change the drain logic.

— hive: backend=omp model=anthropic/claude-opus-5-5


🐝 Hive Agent: contributor | SHA: 6902ead4e

…legacy drain

Drained CLI-memory facts are agent-written text, so while one is still a
draft it never reaches an agent, whatever include_states admits:

- FilterByLifecycleFor (kick primer, knowledge advisor) drops it even for
  a draft-admitting scope or primer config, or an author match. The
  operator filter FilterByLifecycle still lists it for review.
- TOCScope.HideAutoMemoryDrafts, set by AgentScope and on every ?agent=
  TOC/entry/effective read, drops it as reason "lifecycle".
- AutoPromoteCandidates skips pages tagged cli-memory.

Review: PUT /api/knowledge/entry/{id}/state now accepts drained entries
(source: cli-memory) in the reserved bead-synth-wiki vault. Before this
change they could never be approved. The dashboard knowledge view gets an
"Auto-memory drafts" filter that shows agent: tags, with owner-only
Approve (approved) and Discard (deprecated, so the memhash blocks a
re-draft).

hivectl knowledge drain-memory --legacy [--truncate] calls the new
owner-only, audited POST /api/knowledge/cli-memory/drain-legacy, which
drains /data/home/.claude/projects/*/memory into drafts tagged
agent:shared. Files are emptied only with --truncate, and only when
every fact in them is stored.

Docs: Auto-memory drafts section in knowledge-lifecycle.md, operator
reference, hivectl, API reference/OpenAPI, the design doc's "Phase 3 as
shipped" section and the design index status. Route citations re-anchored
with check-docs-citations.py --fix.

Hive-Run: hivecommons#17058
Hive-Plan: cli-memory-drain.md#phase-3--review-flow-draft-exclusion-legacy-migration-operator-docs
Hive-Spec: cli-memory-drain#phase-3
Signed-off-by: Karibhou <Karibhou@users.noreply.github.com>
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Nov 7, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

@Karibhou this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • test (dashboard 3/4)
  • test (dashboard 4/4)
  • test (dashboard shuffle 1/3)
  • test (dashboard shuffle 2/3)
    Review asks:
  • the review swarm requested changes

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the diff against v5 at 4f6cd05 plus the callers (knowledge/primer.go:161, dashboard/api_knowledge.go:425,438, knowledge/filestore.go:691-694). The exclusion logic is sound; the PR is blocked only by two red dashboard shards, and both are caused by this PR's own code, so they're a quick fix.

1. TestKnowledgeDrainLegacyMemory fails: drained entry missing "repo:hivecommons/hive" (dashboard/api_knowledge_cli_memory_test.go:134)

repoFromClaudeSlug (knowledge/climemory/drain.go:324-335) finds the project slug by scanning for a path segment literally named projects and taking the next one. The test points legacyClaudeProjectsDir at t.TempDir() (…_test.go:98-100), so the path is /tmp/TestKnowledgeDrainLegacyMemory…/001/-data-agents-scanner-hivecommons-hive/memory/MEMORY.md — no projects segment, slug is "", no repo: tag. Production (/data/home/.claude/projects/<slug>/memory) does have the segment, so the handler works there; it's the fixture that diverges. Smallest fix: projects := filepath.Join(t.TempDir(), "projects"). More robust, and arguably what the legacy entry point should do anyway: have LegacyClaudeSources (climemory/legacy.go:21-41) hand the drainer the slug it already has in e.Name() instead of re-deriving it from the path — but that touches #17086's drainer, so the fixture fix is fine for this PR.

2. TestSettingsDialogReferencesEveryHiveYAMLLeaf fails (dashboard/settings_parity_test.go:40): settings parity allowlist still contains "agents.cli_memory.drain_to_knowledge", but the Settings UI now references it.

The parity corpus is static/index.html plus every .go file under pkg/dashboard (settings_parity_test.go:45-55). Your 409 message at dashboard/api_knowledge_cli_memory.go:41 spells out agents.cli_memory.drain_to_knowledge as a literal, so the guard now believes the Settings dialog exposes that key. Either drop the dotted key from the error string (e.g. "…or enable the CLI-memory drain in hive.yaml…") or, if you actually want a Settings control for it, remove the allowlist line. Don't remove the allowlist line without adding the control — that's the state the guard is there to catch.

What I verified and found correct

  • Kick path: primer.go:161 is the only primer caller and uses FilterByLifecycleFor, where lifecycleAllowedFor (lifecycle.go:140-142) now rejects a draft with IsAutoMemory(f) before either the include list or the author match can admit it. Operator search (api_knowledge.go:425,438) uses FilterByLifecycle, which no longer delegates to the For variant, so include_states=draft still lists drafts for review. The split is correct.
  • IsAutoMemory keys on Fact.Origin, which filestore.go:691-694 fills from source_url falling back to source. The drainer writes source: cli-memory (drain.go:183) and no source_url, so Origin == "cli-memory" holds, and the tag check is a second route anyway.
  • writableVaultHolding (api.go:469-478) now reads the page before deciding on the reserved vault and only admits Origin == cli-memory, so synthesizer entries there are still refused. Good.
  • ?agent= TOC/entry/effective reads set HideAutoMemoryDrafts (api_knowledge_toc.go:29), and AgentScope sets it unconditionally (toc.go:101); ExclusionReason reports lifecycle for them.
  • New route is owner-only, audited, added to the deny table; truncation is opt-in and only empties files whose every memhash is already in the vault (legacy.go:76-88), with symlinked stores skipped. Nothing here touches a trust surface.

Once the two tests are green this looks correct to me. I have not approved or changed anything.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#17123 ✨ knowledge: finish CLI memory drain phase 1 — dedup tags, spool, draft create path CONFLICT src/docs/api-reference/knowledge.md
src/docs/design/README.md

@hivecommons-hive

Copy link
Copy Markdown
Contributor

CI triage (scanner): head 6902ead. Both failures are deterministic (3/3 reruns) and come from this PR's own code. No local run was done; this is from the CI log and source.

1. TestKnowledgeDrainLegacyMemory

api_knowledge_cli_memory_test.go:134: drained entry missing "repo:hivecommons/hive":
  tags: [cli-memory, cli:claude, memhash:577f…, agent:shared]

Cause: the test's temp dir is <tmp>/TestX/001/-data-agents-scanner-hivecommons-hive/memory/MEMORY.md. repoFromClaudeSlug (pkg/knowledge/climemory/drain.go:324-335) only derives the slug from a path component named exactly projects, and there is none, so the repo is "" and no repo: tag is written. Production (/data/home/.claude/projects/...) is fine. Only the fixture is wrong.

Fix in src/pkg/dashboard/api_knowledge_cli_memory_test.go (TestKnowledgeDrainLegacyMemory, ~line 97):

-	projects := t.TempDir()
+	projects := filepath.Join(t.TempDir(), "projects")

MkdirAll on memFile already creates it.

2. TestSettingsDialogReferencesEveryHiveYAMLLeaf

settings_parity_test.go:40: settings parity allowlist still contains "agents.cli_memory.drain_to_knowledge", but the Settings UI now references it; remove the allowlist entry

Cause: the parity corpus is static/index.html plus every *.go file in pkg/dashboard (settings_parity_test.go:46-60). The new 409 message at src/pkg/dashboard/api_knowledge_cli_memory.go:41 contains the literal agents.cli_memory.drain_to_knowledge. That counts as a "reference", but there is still no Settings control, so the # TODO #11854 allowlist entry (settings_parity_allowlist.txt:155) now trips the check.

Fix (recommended): keep the allowlist entry, because there is still no UI control. Reword the message so it doesn't embed the dotted path:

-		jsonError(w, "the bead-synth-wiki vault is not connected; configure bead stores or set agents.cli_memory.drain_to_knowledge so drained drafts land in a vault the primer reads", http.StatusConflict)
+		jsonError(w, "the bead-synth-wiki vault is not connected; configure bead stores or enable the CLI-memory drain_to_knowledge option so drained drafts land in a vault the primer reads", http.StatusConflict)

Check that api_knowledge_cli_memory_test.go and the docs don't assert the old string. I saw no such assertion, but only the 409 status is checked in the drain test.

Alternative: if you'd rather leave the message alone, delete line 155 of src/pkg/dashboard/settings_parity_allowlist.txt (agents.cli_memory.drain_to_knowledge # TODO #11854). That silences the check without adding a control. Line 124, agents.<key>.cli_memory.drain_to_knowledge, is a different leaf and stays.

coverage and test are red only because of these two shards.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Superseded by hive: re-authored as #17141 with the same commits and sign-off because the author's clanker is offline. This PR is closed; if #17141 fails, hive reopens it.

@hivecommons-hive hivecommons-hive Bot added the hive/superseded Closed by Hive: a different merged PR already landed this change label Nov 8, 2026
@hivecommons-hive hivecommons-hive Bot closed this Nov 8, 2026
@Karibhou
Karibhou deleted the feat/cli-memory-drain-phase3 branch November 15, 2026 11:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

conflicts-with-open-pr Open PR has a merge conflict with another open PR dco-signoff: yes Indicates the PR's author has signed the DCO. hive/superseded Closed by Hive: a different merged PR already landed this change size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[scanner] ✨ knowledge: review flow + never-prime for auto-memory drafts, legacy migration, operator docs (phase 3 of #17033)

1 participant