Skip to content

📖 docs(design): drain CLI auto-memory into draft knowledge beads - #17061

Merged
clubanderson merged 1 commit into
v5from
scanner/fix-17033
Nov 7, 2026
Merged

clubanderson merged 1 commit into
v5from
scanner/fix-17033

Conversation

@hivecommons-hive

@hivecommons-hive hivecommons-hive Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Why

Each coding CLI keeps a hidden, per-agent memory store: Claude Code projects/*/memory/MEMORY.md, Codex $CODEX_HOME/memories, Gemini GEMINI.md. Nothing in those stores is reviewed or scoped, and none of it goes through the knowledge lifecycle. As raised at the 2026-11-05 community meeting, much of it should have been beads. Hive already has the destination: knowledge facts with draft/approved/deprecated/superseded states, knowledge.agent_scopes, the kick primer, and the curator. This PR adds the design for the missing drain, which moves memory-store entries into draft knowledge facts and then empties the store.

What's in the PR

  • New src/docs/design/cli-memory-drain.md (design only), covering:
    • the drain per CLI: a Claude Code SessionEnd hook, with PostToolUse as an option; a manager-side drain for Codex and Gemini in deliverKickLocked, before ✨ agents: disable CLI auto-memory by default and add cli_memory.clear_on_kick #17040's clearCLIMemoryLocked. Copilot CLI has no local store, so there is nothing to drain.
    • the bead shape: --type knowledge --state draft --tag auto-memory --tag agent:<name>, plus cli: and memhash: tags.
    • the write-side gaps that phase 1 closes: bd create has no knowledge type, and CreateFactRequest has no state.
  • knowledge-system.md open question 5 is answered and linked to the new doc.
  • The new doc is indexed in src/docs/design/README.md.

Decisions on #17033's open questions (the maintainer can override any of them)

  1. Dedup across agents: content-hash dedup at create time, checked across all lifecycle states. If a second agent drains the same hash, it gets an agent:<name> tag on the existing fact instead of a new bead. A discarded fact is never revived. Semantic merge is left to the reviewer (superseded_by).
  2. Curator vs a separate hook: the drain is ingest-only and only ever creates drafts. The existing knowledge.curator and the state API remain the only path to approved; there is no second curator.
  3. Prompt injection: drained text is treated as untrusted. The body is stored verbatim and never interpreted, and tags come from an allow-list. Drafts are hard-excluded from every kick, primer, agent-facing TOC read and the public MCP, even when include_states admits draft, until a fact is approved.

Implementation (child sub-issues of #17033)

Docs only, so there is no changelog fragment.

Fixes #17033 (design delivered here; implementation tracked in child issues #17056, #17057, #17058)

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

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: clubanderson <407614+clubanderson@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 7, 2026
@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 danathar 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 the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 7, 2026
@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
#17063 📝 proposal: Nous → Spek — the winning experiment as a spek-new source same files src/docs/design/README.md

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 7, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor Author

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

hive/awaiting-ci: CI pending — sweep will merge when green.


🐝 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

Evidence bundle `#17061bb90d62` sha256:30497b1d0ad5c98765abd3bae1bd4448a5c5706b18ea02b83a5c4da8f81f5a12 — download from the dashboard or `hivectl review evidence #17061`.

@hivecommons-hive hivecommons-hive Bot added the role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) label Nov 7, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Spot-checked ~20 of the file:line citations against 7a929356 (the commit the doc pins) — lifecycle.go:16-21/88-98, primer.go:144, knowledge_config.go:43-46/269, kick_priming.go:256, api.go:389, api_knowledge.go:577, knowledge/api.go:293-300/335-344, manager_kick.go:242/271, manager_homes.go:582/624, claude_remote_control.go:44-46, promote.go:127, curator_schedule.go:31, beads-cli.md:11 — all resolve to the symbols the doc names. The two write-side gaps it identifies are real: CreateFactRequest has no state field, and bd create has no knowledge type. Design reads sound to me; nothing blocking.

One currency note, since the doc will outlive the queue: #17039 merged to v5 as 943d807 after this was written. src/docs/design/cli-memory-drain.md says (lines 8-11, 24-27) that #17039 is an open PR and that "v5 bridges ~/.claude, ~/.gemini and ~/.codex whole into the shared home (interactive_home.go:68-71)". On current v5, interactiveHomeBridgeDirs (src/crux/agent/interactive_home.go:73-76) is .config, .codex, .cache — .claude/.gemini are no longer bridged. The pinned-commit framing keeps the citations honest, but a one-line "#17039 has since landed" would stop a reader from concluding the sharing problem is still live. #17040 is still open, so that half stands.

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

@hivecommons-hive hivecommons-hive Bot added stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 7, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor Author

Needs a decision, not a merge: the lane reported merge-train:claim-conflict#17086:17033/0:0/0:.

Head: verdict approved @bb90d62, 70/70 checks green, DCO yes, soak 10m0s elapsed.

How to release it:

  • A maintainer must resolve the lane condition named above or review and merge manually; /hive approve does not override that condition.

Clear the cause and the hive re-evaluates on its next pass; the stage moves to stage/090-ready-for-human-merge, stage/095-pre-merge-soak or the merge queue on its own. Approval does not bypass CI, hold labels or other merge gates.

@clubanderson
clubanderson merged commit e4cc8e4 into v5 Nov 7, 2026
98 of 103 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-17033 branch November 7, 2026 20:11
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/L Denotes a PR that changes 100-499 lines, ignoring generated files. stage/085-needs-decision A human decision is owed: sentinel alert, hold/needs-decision label, human-only rule or parked issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ knowledge: drain CLI auto-memory into beads/knowledge at session end instead of hidden MEMORY.md

1 participant