Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- CLI memory drain, phase 1 completion (#17056): a fact already in the vault now gains the draining agent's `agent:<name>` tag instead of being ignored, and keeps whatever state an operator gave it, so a deprecated memory is never revived. A memory file whose facts did not all reach the vault (vault unwritable, 200-facts-per-drain cap) is copied to `/data/knowledge/auto-memory-spool/<agent>/` before `clear_on_kick` wipes the store and retried on the agent's next drain; the drain log line now reports `spooled S`. `POST /api/knowledge/create` takes `state` (`approved` default, or `draft`, which is written into the local channel named by `layer` and never overwrites an existing entry) and accepts a `cli-memory`-tagged fact only as a draft carrying the drain's own tags. `bd create --type knowledge [--state] [--tag]… [--layer]` creates a fact through that endpoint.
156 changes: 156 additions & 0 deletions src/cmd/bd/create_knowledge.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
package main

import (
"encoding/json"
"errors"
"flag"
"fmt"
"io"
"os"
"strings"
)

// knowledgeCreateType is the `bd create --type` value that creates a
// knowledge fact instead of a bead (#17056). Facts live in the knowledge
// store the curator, the TOC and `hivectl knowledge state` work on, so this
// goes to the dashboard's POST /api/knowledge/create, the same way `bd kb`
// does, never into the local bead store.
const knowledgeCreateType = "knowledge"

// maxKnowledgeBodyBytes bounds --body-file; a fact is a note, not a document
// (use `bd kb import-file` for those).
const maxKnowledgeBodyBytes = 256 * 1024

// knowledgeCreateRequest is the body of POST /api/knowledge/create. Empty
// fields are omitted so the dashboard applies its defaults (layer project,
// type pattern, state approved).
type knowledgeCreateRequest struct {
Title string `json:"title"`
Body string `json:"body"`
Type string `json:"type,omitempty"`
Tags []string `json:"tags,omitempty"`
Layer string `json:"layer,omitempty"`
State string `json:"state,omitempty"`
}

// stringList is a repeatable string flag.
type stringList []string

func (s *stringList) String() string { return strings.Join(*s, ",") }

func (s *stringList) Set(v string) error {
*s = append(*s, v)
return nil
}

// createTypeArg returns the value of the last --type/-type flag in args
// (Go's flag package keeps the last one), or "" when there is none.
func createTypeArg(args []string) string {
typ := ""
for i := 0; i < len(args); i++ {
a := args[i]
if a == "--" {
break
}
name := strings.TrimLeft(a, "-")
if name == a {
continue
}
if v, ok := strings.CutPrefix(name, "type="); ok {
typ = v
continue
}
if name == "type" && i+1 < len(args) {
typ = args[i+1]
i++
}
}
return typ
}

// parseKnowledgeCreate turns `bd create --type knowledge …` arguments into
// the request body. stdin is read for --body-file -.
func parseKnowledgeCreate(args []string, stdin io.Reader) (knowledgeCreateRequest, error) {
fs := flag.NewFlagSet("create", flag.ContinueOnError)
fs.SetOutput(io.Discard)
fs.String("type", knowledgeCreateType, "must be knowledge")
title := fs.String("title", "", "Fact title (required)")
body := fs.String("body", "", "Fact body")
bodyFile := fs.String("body-file", "", "Read the fact body from a file (- for stdin)")
state := fs.String("state", "", "Lifecycle state to create the fact in: draft or approved (default approved)")
layer := fs.String("layer", "", "Knowledge layer, or for a draft the local channel to write to (default project)")
factType := fs.String("fact-type", "", "Fact type, e.g. pattern, gotcha, decision (default pattern)")
var tags stringList
fs.Var(&tags, "tag", "Tag to attach (repeatable)")
if err := fs.Parse(args); err != nil {
return knowledgeCreateRequest{}, err
}
if fs.NArg() > 0 {
return knowledgeCreateRequest{}, fmt.Errorf("unexpected argument %q", fs.Arg(0))
}
if strings.TrimSpace(*title) == "" {
return knowledgeCreateRequest{}, errors.New("--title is required")
}
if (*body == "") == (*bodyFile == "") {
return knowledgeCreateRequest{}, errors.New("exactly one of --body and --body-file is required")
}
text := *body
if *bodyFile != "" {
var r io.Reader = stdin
if *bodyFile != "-" {
f, err := os.Open(*bodyFile)
if err != nil {
return knowledgeCreateRequest{}, err
}
defer func() { _ = f.Close() }()
r = f
}
data, err := io.ReadAll(io.LimitReader(r, maxKnowledgeBodyBytes+1))
if err != nil {
return knowledgeCreateRequest{}, fmt.Errorf("reading --body-file: %w", err)
}
if len(data) > maxKnowledgeBodyBytes {
return knowledgeCreateRequest{}, fmt.Errorf("--body-file is over %d bytes", maxKnowledgeBodyBytes)
}
text = string(data)
}
if strings.TrimSpace(text) == "" {
return knowledgeCreateRequest{}, errors.New("the fact body is empty")
}
return knowledgeCreateRequest{
Title: *title,
Body: text,
Type: *factType,
Tags: tags,
Layer: *layer,
State: strings.ToLower(strings.TrimSpace(*state)),
}, nil
}

func cmdCreateKnowledge(args []string) {
req, err := parseKnowledgeCreate(args, os.Stdin)
if err != nil {
fmt.Fprintf(os.Stderr, "bd create --type knowledge: %v\n", err)
os.Exit(1)
}
payload, err := json.Marshal(req)
if err != nil {
fmt.Fprintf(os.Stderr, "bd create --type knowledge: %v\n", err)
os.Exit(1)
}
body, err := kbPost(dashboardURL()+"/api/knowledge/create", string(payload))
if err != nil {
fmt.Fprintf(os.Stderr, "bd create --type knowledge: %v\n", err)
os.Exit(1)
}
var resp struct {
Title string `json:"title"`
Layer string `json:"layer"`
State string `json:"state"`
}
if err := json.Unmarshal(body, &resp); err != nil {
fmt.Fprintf(os.Stderr, "bd create --type knowledge: invalid response: %v\n", err)
os.Exit(1)
}
fmt.Printf("Created knowledge fact %q in %s (state: %s)\n", resp.Title, resp.Layer, resp.State)
}
88 changes: 88 additions & 0 deletions src/cmd/bd/create_knowledge_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
package main

import (
"encoding/json"
"net/http"
"os"
"path/filepath"
"reflect"
"strings"
"testing"
)

func TestCreateTypeArg(t *testing.T) {
cases := []struct {
args []string
want string
}{
{[]string{"--title", "x", "--type", "knowledge"}, "knowledge"},
{[]string{"-type=knowledge", "--title", "x"}, "knowledge"},
{[]string{"--type", "task", "--type=knowledge"}, "knowledge"},
{[]string{"--type=knowledge", "--type", "bug"}, "bug"},
{[]string{"--title", "x"}, ""},
{[]string{"--", "--type", "knowledge"}, ""},
}
for _, tc := range cases {
if got := createTypeArg(tc.args); got != tc.want {
t.Errorf("createTypeArg(%q) = %q, want %q", tc.args, got, tc.want)
}
}
}

func TestParseKnowledgeCreate(t *testing.T) {
bodyFile := filepath.Join(t.TempDir(), "entry.md")
if err := os.WriteFile(bodyFile, []byte("from a file\n"), 0o644); err != nil {
t.Fatal(err)
}
got, err := parseKnowledgeCreate([]string{
"--type", "knowledge", "--title", "T", "--body-file", bodyFile,
"--state", "Draft", "--tag", "cli-memory", "--tag", "agent:scanner", "--layer", "drafts",
}, strings.NewReader(""))
if err != nil {
t.Fatal(err)
}
want := knowledgeCreateRequest{Title: "T", Body: "from a file\n", Tags: []string{"cli-memory", "agent:scanner"}, Layer: "drafts", State: "draft"}
if !reflect.DeepEqual(got, want) {
t.Fatalf("got %+v\nwant %+v", got, want)
}

if got, err := parseKnowledgeCreate([]string{"--title", "T", "--body-file", "-"}, strings.NewReader("stdin body")); err != nil || got.Body != "stdin body" {
t.Fatalf("stdin body: %+v %v", got, err)
}

for _, args := range [][]string{
{"--body", "b"}, // no title
{"--title", "T"}, // no body
{"--title", "T", "--body", "b", "--body-file", bodyFile}, // both bodies
{"--title", "T", "--body", " "}, // blank body
{"--title", "T", "--body", "b", "extra"}, // stray argument
{"--title", "T", "--body", "b", "--priority", "1"}, // bead-only flag
} {
if _, err := parseKnowledgeCreate(args, strings.NewReader("")); err == nil {
t.Errorf("parseKnowledgeCreate(%q) accepted", args)
}
}
}

// bd create --type knowledge posts to the dashboard, not the bead store.
func TestCmdCreateKnowledgePostsToDashboard(t *testing.T) {
t.Setenv("BD_DIR", t.TempDir())
var got map[string]any
kbTestServer(t, func(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost || r.URL.Path != "/api/knowledge/create" {
t.Errorf("request = %s %s", r.Method, r.URL.Path)
}
if err := json.NewDecoder(r.Body).Decode(&got); err != nil {
t.Errorf("decoding request: %v", err)
}
jsonResponse(t, w, map[string]any{"ok": true, "title": "T", "layer": "drafts", "state": "draft"})
})
cmdCreate([]string{"--type", "knowledge", "--title", "T", "--body", "b", "--state", "draft", "--tag", "cli-memory", "--layer", "drafts"})
want := map[string]any{"title": "T", "body": "b", "state": "draft", "tags": []any{"cli-memory"}, "layer": "drafts"}
if !reflect.DeepEqual(got, want) {
t.Fatalf("payload = %v, want %v", got, want)
}
if entries, _ := os.ReadDir(os.Getenv("BD_DIR")); len(entries) != 0 {
t.Fatalf("knowledge create touched the bead store: %d entries", len(entries))
}
}
9 changes: 8 additions & 1 deletion src/cmd/bd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,9 @@ Commands:
list [--json] [--status=<s>] [--actor=<a>] List beads
ready [--json] [--actor=<a>] List open/unblocked beads
create --title "..." --type <type> --priority <0-4> --actor <name> [--external-ref <ref>]
create --type knowledge --title "..." (--body "..." | --body-file <path|->)
[--state draft|approved] [--tag <tag>]... [--layer <channel>] [--fact-type <type>]
Create a knowledge fact via the dashboard API
update <id> --claim Claim a bead (set in_progress)
update <id> --status <status> Change status
update <id> --set-metadata key=value Set metadata key
Expand Down Expand Up @@ -177,9 +180,13 @@ func cmdReady(args []string) {
// ---------- create ----------

func cmdCreate(args []string) {
if createTypeArg(args) == knowledgeCreateType {
cmdCreateKnowledge(args)
return
}
fs := flag.NewFlagSet("create", flag.ExitOnError)
title := fs.String("title", "", "Bead title (required)")
beadType := fs.String("type", "task", "Bead type: bug|feature|task|epic|chore|decision|advisory")
beadType := fs.String("type", "task", "Bead type: bug|feature|task|epic|chore|decision|advisory|knowledge")
priority := fs.Int("priority", 2, "Priority 0-4 (0=critical, 4=minor)")
actor := fs.String("actor", "", "Actor name (required)")
extRef := fs.String("external-ref", "", "External reference (e.g. issue URL)")
Expand Down
9 changes: 8 additions & 1 deletion src/cmd/hive/boot_cli_memory_drain.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ import (
// and registered under; CLI-memory drafts land in the same store.
const beadSynthVaultName = "bead-synth-wiki"

// cliMemorySpoolDir keeps a copy of memory files whose facts could not all
// be stored, per agent, so clear_on_kick does not lose them; the drainer
// retries them on the agent's next drain (#17056). A var so tests can point
// it at a temp dir.
var cliMemorySpoolDir = "/data/knowledge/auto-memory-spool"

// cliMemoryDrainEnabled reports whether any enabled agent drains its CLI
// memory into the knowledge store (agents.cli_memory.drain_to_knowledge,
// fleet-wide or per agent).
Expand Down Expand Up @@ -67,7 +73,7 @@ func (b *boot) installCLIMemoryDrainer() {
if layer == "" {
layer = knowledge.LayerPersonal
}
drainer := &climemory.Drainer{Dir: vaultPath, Store: b.knowledgeAPI.GetVaultStore(vaultPath), Layer: layer}
drainer := &climemory.Drainer{Dir: vaultPath, Store: b.knowledgeAPI.GetVaultStore(vaultPath), Layer: layer, SpoolDir: cliMemorySpoolDir}
cfg := b.cfg
host.SetCLIMemoryDrainer(func(req crux.CLIMemoryDrainRequest) crux.CLIMemoryDrainResult {
sources := make([]climemory.Source, 0, len(req.Sources))
Expand All @@ -80,6 +86,7 @@ func (b *boot) installCLIMemoryDrainer() {
Drained: res.Drained,
Dupes: res.Dupes,
Skipped: res.Skipped,
Spooled: res.Spooled,
Err: errors.Join(res.Errors...),
}
})
Expand Down
3 changes: 3 additions & 0 deletions src/cmd/hive/boot_cli_memory_drain_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,9 @@ func TestInstallCLIMemoryDrainerWritesDraftsIntoBeadSynthVault(t *testing.T) {
cfg := bootKnowledgeConfig(t)
cfg.AgentsCLIMemory.DrainToKnowledge = true
cfg.Knowledge.BeadSynthesizer.TargetLayer = "team"
prevSpool := cliMemorySpoolDir
cliMemorySpoolDir = t.TempDir()
t.Cleanup(func() { cliMemorySpoolDir = prevSpool })
b := newBootKnowledgeBoot(t, cfg)
var log strings.Builder
b.logger = slog.New(slog.NewTextHandler(&log, nil))
Expand Down
8 changes: 4 additions & 4 deletions src/crux/agent/cli_memory_drain.go
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ func cliMemoryDrainSources(agent *AgentProcess, backend string) []CLIMemorySourc
// best-effort: a failed drain is logged and the kick proceeds. The one log
// line per drain is
//
// cli-memory: drained N facts from <agent> into <store> (dupes K)
// cli-memory: drained N facts from <agent> into <store> (dupes K, spooled S)
func (m *Manager) drainCLIMemoryForKick(agent *AgentProcess, backend string) {
if !agent.Config.CLIMemory.DrainMemoryToKnowledge() {
return
Expand All @@ -97,8 +97,8 @@ func (m *Manager) drainCLIMemoryForKick(agent *AgentProcess, backend string) {
m.logger.Warn("cli-memory: drain failed before kick",
"agent", agent.Name, "store", res.Store, "drained", res.Drained, "error", res.Err)
}
m.logger.Info(fmt.Sprintf("cli-memory: drained %d facts from %s into %s (dupes %d)",
res.Drained, agent.Name, res.Store, res.Dupes),
m.logger.Info(fmt.Sprintf("cli-memory: drained %d facts from %s into %s (dupes %d, spooled %d)",
res.Drained, agent.Name, res.Store, res.Dupes, res.Spooled),
"agent", agent.Name, "store", res.Store, "drained", res.Drained,
"dupes", res.Dupes, "skipped", res.Skipped, "sources", len(sources))
"dupes", res.Dupes, "skipped", res.Skipped, "spooled", res.Spooled, "sources", len(sources))
}
5 changes: 4 additions & 1 deletion src/crux/cli_memory_drain.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,16 @@ type CLIMemoryDrainRequest struct {
}

// CLIMemoryDrainResult is what the drainer reports back for the runtime's
// one log line per drain.
// one log line per drain. Spooled counts memory files kept in the hive's
// spool because not all of their facts were stored; they are retried on the
// agent's next drain, so the wipe that follows the drain does not lose them.
type CLIMemoryDrainResult struct {
// Store is the knowledge store (vault path or name) the drafts landed in.
Store string
Drained int
Dupes int
Skipped int
Spooled int
Err error
}

Expand Down
4 changes: 2 additions & 2 deletions src/docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -649,9 +649,9 @@ agents:
| `auto_memory` | `false` | When false hive pins the vendor switch off at launch: Claude Code gets `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` in its environment ([docs](https://code.claude.com/docs/en/memory)); Codex gets `[features] memories = false` merged into `$CODEX_HOME/config.toml` ([docs](https://developers.openai.com/codex/memories)); Copilot CLI gets `"memory": false` in its per-agent `~/.copilot/settings.json` (`copilot help config`). `true` writes the opposite pin so an operator's own setting is never silently shadowed. Gemini CLI has no equivalent switch. |
| `clear_on_kick` | `false` | Before every non-resume kick (next to the `/clear` sent by `clear_on_kick`), remove this agent's `~/.claude/projects/*/memory/`, `$CODEX_HOME/memories*/`, and `~/.gemini/GEMINI.md`. Only the per-agent home under `/data/home/agents/<name>` is touched; nothing under the shared `/data/home` is removed, and agents running with `HIVE_SHARED_AGENT_HOME=1` or as uid 0 are skipped. Copilot memory is server-side and has no local store. |

| `drain_to_knowledge` | `false` | Before every non-resume kick, and before `clear_on_kick` wipes anything, read this agent's Claude `~/.claude/projects/*/memory/` (`MEMORY.md` plus topic files), Codex `$CODEX_HOME/memories*/` and the `## Gemini Added Memories` section of `~/.gemini/GEMINI.md`, and write each bullet or paragraph as a **draft** entry in the `bead-synth-wiki` vault (`knowledge.bead_synthesizer.vault_path`, default `/data/vaults/bead-synth-wiki`) with `source: cli-memory`, `agent: <name>`, `cli: <claude\|codex\|gemini>` and, when the Claude project slug ends in one of the agent's repos, `repo: <org/repo>`. Entries are deduplicated by a SHA-256 of the normalised text (`memhash`), so repeated drains and the same fact from several agents produce one entry; an entry an operator approved, deprecated or renamed is still a duplicate. Drafts never reach a kick until a human approves them ([#17033](https://github.com/hivecommons/hive/issues/17033)). Needs the in-process crux runtime. |
| `drain_to_knowledge` | `false` | Before every non-resume kick, and before `clear_on_kick` wipes anything, read this agent's Claude `~/.claude/projects/*/memory/` (`MEMORY.md` plus topic files), Codex `$CODEX_HOME/memories*/` and the `## Gemini Added Memories` section of `~/.gemini/GEMINI.md`, and write each bullet or paragraph as a **draft** entry in the `bead-synth-wiki` vault (`knowledge.bead_synthesizer.vault_path`, default `/data/vaults/bead-synth-wiki`) with `source: cli-memory`, `agent: <name>`, `cli: <claude\|codex\|gemini>` and, when the Claude project slug ends in one of the agent's repos, `repo: <org/repo>`. Entries are deduplicated by a SHA-256 of the normalised text (`memhash`), so repeated drains and the same fact from several agents produce one entry, which gains an `agent:<name>` tag per draining agent; an entry an operator approved, deprecated or renamed is still a duplicate and keeps its state. A memory file whose facts did not all reach the vault (vault unwritable, 200-facts-per-drain cap) is copied to `/data/knowledge/auto-memory-spool/<agent>/` before the wipe and retried on the next drain ([#17056](https://github.com/hivecommons/hive/issues/17056)). Drafts never reach a kick until a human approves them ([#17033](https://github.com/hivecommons/hive/issues/17033)). Needs the in-process crux runtime. |

Set `auto_memory: true` on a single agent to let it keep a private notebook while the rest of the fleet stays stateless between kicks. The knobs are independent: `auto_memory: true` with `clear_on_kick: true` gives a memory that lives for exactly one kick, and adding `drain_to_knowledge: true` is the "memory → beads" flow: the CLI may take notes during a turn, every note becomes a reviewable draft at the next kick, and the private store is then emptied. The log line per drain is `cli-memory: drained N facts from <agent> into bead-synth-wiki (dupes K)`.
Set `auto_memory: true` on a single agent to let it keep a private notebook while the rest of the fleet stays stateless between kicks. The knobs are independent: `auto_memory: true` with `clear_on_kick: true` gives a memory that lives for exactly one kick, and adding `drain_to_knowledge: true` is the "memory → beads" flow: the CLI may take notes during a turn, every note becomes a reviewable draft at the next kick, and the private store is then emptied. The log line per drain is `cli-memory: drained N facts from <agent> into bead-synth-wiki (dupes K, spooled S)`.

Every Model Gateway (and the bob backend) also accepts an optional `key_name` — a human-chosen LABEL for the configured key, e.g. `key_name: openrouter-prod-key`. It is safe-to-show metadata, not a secret: the dashboard's gateway row displays it as "Using key: `<name>`", or "(unnamed)" when no label is set, so operators can tell keys apart without ever seeing the value. For gateway keys, the row and settings/status APIs also expose `keySHA256`, the lowercase SHA-256 of the exact effective key string Hive will inject through the inference proxy; this lets operators compare Hive with LiteLLM/OpenRouter key-hash displays without revealing the secret. Saving a replacement key refreshes live inference proxy routes for running agents, so the next kick uses the new key without an agent restart. See [`inference-backends.md`](../../docs/inference-backends.md) for a full YAML example.

Expand Down
Loading
Loading