brigade-cli 0.5.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- brigade/__init__.py +3 -0
- brigade/__main__.py +5 -0
- brigade/cli.py +258 -0
- brigade/config.py +65 -0
- brigade/doctor.py +393 -0
- brigade/fragments.py +64 -0
- brigade/handoff.py +23 -0
- brigade/ingest.py +298 -0
- brigade/install.py +217 -0
- brigade/prompt.py +135 -0
- brigade/py.typed +0 -0
- brigade/reconfigure.py +64 -0
- brigade/registry.py +39 -0
- brigade/scrub.py +90 -0
- brigade/selection.py +66 -0
- brigade/station.py +36 -0
- brigade/status.py +24 -0
- brigade/templates/claude/memory-handoffs/TEMPLATE.md +57 -0
- brigade/templates/codex/memory-handoffs/TEMPLATE.md +57 -0
- brigade/templates/depth/repo.json +12 -0
- brigade/templates/depth/workspace.json +30 -0
- brigade/templates/generic/harness-adapter-checklist.md +55 -0
- brigade/templates/generic/memory-contract.md +41 -0
- brigade/templates/harnesses/claude.json +12 -0
- brigade/templates/harnesses/codex.json +11 -0
- brigade/templates/harnesses/hermes.json +16 -0
- brigade/templates/harnesses/openclaw.json +17 -0
- brigade/templates/hermes/README.md +25 -0
- brigade/templates/hermes/memory-handoff.harness.json +36 -0
- brigade/templates/hermes/model-lanes.harness.json +17 -0
- brigade/templates/hermes/workspace.harness.json +30 -0
- brigade/templates/hooks/pre-push +36 -0
- brigade/templates/includes/publisher.json +15 -0
- brigade/templates/memory/cards/backup-restic.md +126 -0
- brigade/templates/memory/cards/chat-surface-crawlers.md +103 -0
- brigade/templates/memory/cards/content-safety.md +54 -0
- brigade/templates/memory/cards/handoff-flow.md +70 -0
- brigade/templates/memory/cards/memory-architecture.md +56 -0
- brigade/templates/memory/cards/memory-care-staleness.md +58 -0
- brigade/templates/memory/cards/memory-scanner.md +98 -0
- brigade/templates/memory/cards/multi-workspace-handoff-admin.md +63 -0
- brigade/templates/memory/cards/obsidian-notes.md +82 -0
- brigade/templates/memory/cards/pipeline-standups.md +88 -0
- brigade/templates/memory/cards/tokenjuice-output-compaction.md +106 -0
- brigade/templates/openclaw/README.md +40 -0
- brigade/templates/openclaw/acp-escalation.openclaw.json +33 -0
- brigade/templates/openclaw/model-aliases.openclaw.json +21 -0
- brigade/templates/openclaw/ollama-memory-search.openclaw.json +24 -0
- brigade/templates/policies/public-content.json +28 -0
- brigade/templates/policies/public-repo.json +27 -0
- brigade/templates/scripts/backup-restic.sh +156 -0
- brigade/templates/skills/note/SKILL.md +173 -0
- brigade/templates/workspace/AGENTS.md +146 -0
- brigade/templates/workspace/CLAUDE.md +48 -0
- brigade/templates/workspace/HEARTBEAT.md +41 -0
- brigade/templates/workspace/IDENTITY.md +27 -0
- brigade/templates/workspace/INSTALL_FOR_AGENTS.md +61 -0
- brigade/templates/workspace/MEMORY.md +102 -0
- brigade/templates/workspace/SAFETY_RULES.md +164 -0
- brigade/templates/workspace/SOUL.md +92 -0
- brigade/templates/workspace/TOOLS.md +116 -0
- brigade/templates/workspace/USER.md +88 -0
- brigade/templates.py +88 -0
- brigade_cli-0.5.0.dist-info/METADATA +211 -0
- brigade_cli-0.5.0.dist-info/RECORD +69 -0
- brigade_cli-0.5.0.dist-info/WHEEL +5 -0
- brigade_cli-0.5.0.dist-info/entry_points.txt +3 -0
- brigade_cli-0.5.0.dist-info/licenses/LICENSE +21 -0
- brigade_cli-0.5.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: memory-scanner
|
|
3
|
+
category: foundation
|
|
4
|
+
tags: [memory, sweep, session-review, promotion, daily-logs]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Memory Scanner
|
|
8
|
+
|
|
9
|
+
The memory scanner is the upstream half of the handoff flow. It is a session-review pass that distills durable knowledge from recent activity (sessions across all your harnesses, daily logs, chat archives) and persists it into canonical memory through the handoff path.
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
sessions daily session logs chat archives
|
|
13
|
+
(Claude Code, (memory/ (discrawl,
|
|
14
|
+
Codex, OpenClaw, YYYY-MM-DD.md) slackcrawl, ...)
|
|
15
|
+
ACP threads)
|
|
16
|
+
\ | /
|
|
17
|
+
\ | /
|
|
18
|
+
v v v
|
|
19
|
+
┌────────────────┐
|
|
20
|
+
│ memory scanner │ cron (typical: nightly)
|
|
21
|
+
│ (session-review│
|
|
22
|
+
│ agent) │
|
|
23
|
+
└────────┬───────┘
|
|
24
|
+
|
|
|
25
|
+
v
|
|
26
|
+
.claude/memory-handoffs/*.md OR direct card writes
|
|
27
|
+
| (only when high-confidence)
|
|
28
|
+
v
|
|
29
|
+
brigade ingest
|
|
30
|
+
|
|
|
31
|
+
v
|
|
32
|
+
memory/cards/, TOOLS.md, USER.md, rules/, .learnings/
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## What it does
|
|
36
|
+
|
|
37
|
+
A real implementation (typical nightly cadence):
|
|
38
|
+
|
|
39
|
+
1. **List recent sessions.** Last 12-24 hours, across all harnesses connected to canonical memory.
|
|
40
|
+
2. **Skip noise.** Cron-spawned sessions, heartbeat/reminder-only sessions, empty subagent shells, pure delivery mirror / announce-only sessions.
|
|
41
|
+
3. **Prioritize real human-facing sessions first.** Discord, WhatsApp, Telegram, Slack, manual ACP threads. These are where decisions, corrections, and preferences actually land.
|
|
42
|
+
4. **Start with summaries.** Only fetch deeper history for sessions that clearly contain durable decisions, corrections, preferences, project changes, new tooling facts, or new published outputs.
|
|
43
|
+
5. **Cap deep review** to the top N most promising sessions (typical: 8) unless there is an obvious reason to exceed it.
|
|
44
|
+
6. **Avoid duplication.** Do not re-promote facts that already exist as cards or in daily-log entries.
|
|
45
|
+
|
|
46
|
+
## What gets persisted
|
|
47
|
+
|
|
48
|
+
- **Update existing cards** when facts changed.
|
|
49
|
+
- **Create new cards** for durable workflows, infra facts, project state, or repeatable lessons.
|
|
50
|
+
- **Append concise timestamped notes** to the relevant daily log if the info is recent and session-specific.
|
|
51
|
+
- **Update `MEMORY.md`** only if the index itself needs to change (new card category, major architecture shift).
|
|
52
|
+
|
|
53
|
+
## What does not get persisted
|
|
54
|
+
|
|
55
|
+
- Banter, casual replies, "yeah" / "ok" exchanges.
|
|
56
|
+
- Anything already covered by an existing card.
|
|
57
|
+
- Speculation, reflections, or unverified findings.
|
|
58
|
+
- Raw transcripts. Transcripts stay in their archive; the scanner produces summary writes, not copies.
|
|
59
|
+
|
|
60
|
+
## Output format
|
|
61
|
+
|
|
62
|
+
The scanner reports back on what it did:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Sessions listed: N
|
|
66
|
+
Sessions deeply reviewed: N
|
|
67
|
+
Sessions with meaningful content: N
|
|
68
|
+
Persisted: [bullets]
|
|
69
|
+
Skipped: [short bullets]
|
|
70
|
+
Net result: [1-3 bullets]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
This gives you an audit trail and a heartbeat for the scanner itself. If "persisted" is empty for a week, either nothing durable happened or the scanner stopped firing.
|
|
74
|
+
|
|
75
|
+
## Scheduling
|
|
76
|
+
|
|
77
|
+
Common cadence (matches reference cookbook): nightly at quiet hours, after [pipeline-standups](pipeline-standups.md) have run and the day's activity has settled.
|
|
78
|
+
|
|
79
|
+
Avoid promoting during active sessions because card writes invalidate prefix caches.
|
|
80
|
+
|
|
81
|
+
## Implementation surface
|
|
82
|
+
|
|
83
|
+
`brigade` ships the contract; it does not ship the scanner agent itself. Wire it as:
|
|
84
|
+
|
|
85
|
+
- a cron job that spawns an isolated agent session with a "review last 12h and persist durable facts" prompt
|
|
86
|
+
- the prompt should embed the skip-rules and cost controls above
|
|
87
|
+
- output goes either directly to `memory/cards/*.md` (if your harness can write there) or through `.claude/memory-handoffs/` for the conservative ingester to route
|
|
88
|
+
|
|
89
|
+
## Relationship to Memory Care
|
|
90
|
+
|
|
91
|
+
The memory scanner captures new durable knowledge. The memory-care staleness loop reviews old cards for drift. Run both: scanner for new facts, staleness checker for old facts that may no longer be true. See [memory-care-staleness](memory-care-staleness.md).
|
|
92
|
+
|
|
93
|
+
## Anti-patterns
|
|
94
|
+
|
|
95
|
+
- **Auto-promoting raw session fragments into `MEMORY.md`.** The index loads on every session; appending fragments nightly bloats it past the bootstrap budget and turns the on-load cache cost into a monthly tax. Write cards instead.
|
|
96
|
+
- **Persisting reflections as facts.** The scanner reads sessions and produces summaries of decisions that happened, not generated commentary on what might have. Promoted findings must be evidence-backed.
|
|
97
|
+
- **Reviewing its own output.** The scanner must skip cron-spawned sessions, heartbeats, announce-only noise, and prior scanner runs. Otherwise it spirals.
|
|
98
|
+
- **Skipping the handoff gates when uncertain.** When confidence is below the auto-promote bar, route through `.claude/memory-handoffs/` and let the ingester apply the same conservative rules everything else gets.
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: multi-workspace-handoff-admin
|
|
3
|
+
category: workflow
|
|
4
|
+
tags: [memory, handoff, multi-workspace, admin]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Multi-Workspace Handoff Admin
|
|
8
|
+
|
|
9
|
+
When one person administers multiple agent homes, only one workspace should own canonical durable memory. Other workspaces can run local sessions, keep local context, and write repo-local notes, but durable facts should flow back to the owner through Memory Handoffs.
|
|
10
|
+
|
|
11
|
+
## Shape
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
managed workspace A managed workspace B repo-local sessions
|
|
15
|
+
.claude/ .claude/ .claude/
|
|
16
|
+
memory-handoffs/ memory-handoffs/ memory-handoffs/
|
|
17
|
+
\ | /
|
|
18
|
+
\ | /
|
|
19
|
+
v v v
|
|
20
|
+
staging inboxes on the canonical memory owner
|
|
21
|
+
|
|
|
22
|
+
v
|
|
23
|
+
brigade ingest
|
|
24
|
+
|
|
|
25
|
+
v
|
|
26
|
+
memory/cards/, TOOLS.md, USER.md, rules/, .learnings/
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Why
|
|
30
|
+
|
|
31
|
+
Multiple active setups drift unless the agents can tell each other what happened. A secondary workspace should not silently become a second source of truth. Its job is to emit handoffs that say what changed, what evidence supports it, and what the canonical owner should remember.
|
|
32
|
+
|
|
33
|
+
## Pull Pattern
|
|
34
|
+
|
|
35
|
+
Run a small trusted sync from the canonical memory owner:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
rsync -a --remove-source-files \
|
|
39
|
+
--include='*.md' --exclude='processed/***' --exclude='*' \
|
|
40
|
+
<remote>:<workspace>/.claude/memory-handoffs/ \
|
|
41
|
+
<canonical-workspace>/pipeline/incoming-handoffs/<remote-label>/
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Then include each staging directory in the ingest loop. Keep remote labels generic, such as `laptop`, `homelab`, `client-a`, or `research-vm`.
|
|
45
|
+
|
|
46
|
+
## Admin Rules
|
|
47
|
+
|
|
48
|
+
- Pull into staging first, then ingest. Do not ingest directly over SSH.
|
|
49
|
+
- Remove remote source files only after successful transfer to the canonical host.
|
|
50
|
+
- Exclude `processed/` so archives do not churn forever.
|
|
51
|
+
- Preserve the original handoff text for review. The canonical owner should see exactly what the remote harness wrote.
|
|
52
|
+
- Use per-source labels so failures can be traced to the workspace that produced them.
|
|
53
|
+
- Surface non-empty pulls to the agents that need to know. A handoff is both memory input and a coordination signal.
|
|
54
|
+
|
|
55
|
+
## Verification
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
find pipeline/incoming-handoffs -name '*.md' -not -path '*/processed/*'
|
|
59
|
+
brigade ingest --target . --dry-run
|
|
60
|
+
ls memory/handoff-inbox/ 2>/dev/null | wc -l
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
If no remote handoffs arrive for a week while remote work is happening, the remote workspace probably lacks the closeout instruction, the sync is broken, or the files are landing in the wrong repo.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: obsidian-notes
|
|
3
|
+
category: foundation
|
|
4
|
+
tags: [obsidian, notes, callouts, vault, sync, knowledge-capture]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Obsidian Notes (Verbatim + Concept)
|
|
8
|
+
|
|
9
|
+
The `/note` skill captures a session's durable knowledge as an Obsidian-formatted markdown file in `~/notes/`, then syncs it to the user's configured Obsidian vault inbox. It is the user-facing complement to the [memory-scanner](memory-scanner.md): cards are for the agent, Obsidian notes are for the human.
|
|
10
|
+
|
|
11
|
+
Full skill spec lives in `skills/note/SKILL.md`. This card explains *when* to use it and the two modes you must distinguish before writing.
|
|
12
|
+
|
|
13
|
+
## Two modes
|
|
14
|
+
|
|
15
|
+
| Mode | Use when | Output style |
|
|
16
|
+
|------|----------|--------------|
|
|
17
|
+
| **Verbatim fix** | Troubleshooting, root-causing, post-incident. Future-you needs the exact commands to reproduce the fix. | `[!bug]` -> `[!success]` -> "How it works" -> `[!warning]` gotchas. Heavy on exact strings and runnable code. |
|
|
18
|
+
| **Summarize / concept** | Learning, capturing a workflow, documenting a system. The reader needs to understand *why* before they trust the *how*. | Overview -> How it works -> Example -> Tips and gotchas. More prose than callouts. |
|
|
19
|
+
|
|
20
|
+
Ask the user which mode applies if it is not obvious. Default to verbatim for bugs and to concept for everything else.
|
|
21
|
+
|
|
22
|
+
## Callout vocabulary
|
|
23
|
+
|
|
24
|
+
Obsidian callouts make the critical parts stick out without breaking prose flow. Use them sparingly. A note should be mostly regular markdown with callouts highlighting the parts that matter.
|
|
25
|
+
|
|
26
|
+
| Callout | Use for |
|
|
27
|
+
|---------|---------|
|
|
28
|
+
| `[!bug]` | Problems, errors, symptoms |
|
|
29
|
+
| `[!success]` | Solutions, fixes, what worked |
|
|
30
|
+
| `[!tip]` | Helpful hints, shortcuts |
|
|
31
|
+
| `[!warning]` | Dangers, things that can break |
|
|
32
|
+
| `[!info]` | Background context |
|
|
33
|
+
| `[!note]` | General annotations |
|
|
34
|
+
| `[!example]` | Practical examples, runnable commands |
|
|
35
|
+
| `[!question]` | Open questions, things to investigate |
|
|
36
|
+
|
|
37
|
+
Syntax:
|
|
38
|
+
|
|
39
|
+
```markdown
|
|
40
|
+
> [!success] Optional title
|
|
41
|
+
> Content.
|
|
42
|
+
> Multi-line is fine.
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## YAML frontmatter (required)
|
|
46
|
+
|
|
47
|
+
```yaml
|
|
48
|
+
---
|
|
49
|
+
tags:
|
|
50
|
+
- tag1
|
|
51
|
+
- tag2
|
|
52
|
+
created: YYYY-MMM-DD
|
|
53
|
+
---
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- 3-5 lowercase, hyphenated tags.
|
|
57
|
+
- Date format `YYYY-MMM-DD` (e.g. `2026-Jan-24`). Not ISO. The vault sorts on this.
|
|
58
|
+
|
|
59
|
+
## Sync target
|
|
60
|
+
|
|
61
|
+
Three common shapes; the user picks one and documents it in `TOOLS.md`:
|
|
62
|
+
|
|
63
|
+
1. **Google Drive + rclone bisync.** `~/notes/` writes propagate to the vault inbox on the next bisync timer fire. Most common for cross-machine vaults.
|
|
64
|
+
2. **Local Obsidian vault on disk.** `cp ~/notes/<slug>.md ~/Obsidian/<Vault>/<Inbox>/`. Same machine only.
|
|
65
|
+
3. **Direct rclone copy.** `rclone copy ~/notes/<slug>.md "gdrive:My Drive/<VaultPath>/<Inbox>/"`. One-shot, no bisync.
|
|
66
|
+
|
|
67
|
+
If no sync target is configured, leave the file in `~/notes/` and surface the path. Do not invent a sync path.
|
|
68
|
+
|
|
69
|
+
## When NOT to use /note
|
|
70
|
+
|
|
71
|
+
- **Durable agent-facing knowledge** -> memory card via the handoff flow, not a vault note. Cards are searched semantically by the agent every session; vault notes are read by humans.
|
|
72
|
+
- **Operational runbook detail** -> `TOOLS.md` or a `rules/*.md` file. The publish gate and memory ingester treat those as canonical.
|
|
73
|
+
- **Sensitive personal context** -> not in `~/notes/` if the vault syncs to a cloud provider. Use the local-only sync path or skip the note entirely.
|
|
74
|
+
|
|
75
|
+
## Relationship to the memory system
|
|
76
|
+
|
|
77
|
+
Vault notes are human-readable references; memory cards are agent-readable durable knowledge. The two have different shapes and different audiences:
|
|
78
|
+
|
|
79
|
+
- A `/note` is written for future-you reading on a phone at a coffee shop.
|
|
80
|
+
- A memory card is written for the agent to retrieve via `memory_search` mid-session.
|
|
81
|
+
|
|
82
|
+
When both apply, write the card first (through the handoff flow) and then optionally write a `/note` if the user will want to reference it outside the workspace. Do not duplicate content.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: pipeline-standups
|
|
3
|
+
category: foundation
|
|
4
|
+
tags: [standups, recap, cron, cross-harness, daily-rhythm]
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Pipeline Standups (Night + Morning)
|
|
8
|
+
|
|
9
|
+
Two short cron-driven sessions that produce a cross-harness daily rhythm: a nightshift standup that summarizes the day before bed, and a morning report that frames the day ahead. They are not memory writes; they are operational summaries delivered to a chat channel so the user can review state at a glance.
|
|
10
|
+
|
|
11
|
+
## Why two
|
|
12
|
+
|
|
13
|
+
A single end-of-day or start-of-day digest works for a single-harness setup. With sessions running across multiple harnesses (Claude Code, Codex, OpenClaw, ACP threads), the user needs a recap that spans them all - and a morning brief that picks up where last night left off.
|
|
14
|
+
|
|
15
|
+
- **Night (typical: 21:00 local).** What got done today. What is uncommitted. What is queued.
|
|
16
|
+
- **Morning (typical: 08:00 local).** Dev servers up/down. Yesterday's highlights. Today's priorities. Any overnight alerts.
|
|
17
|
+
|
|
18
|
+
## Nightshift standup
|
|
19
|
+
|
|
20
|
+
Prompt shape:
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
Nightshift standup. Read these files and produce a brief status report:
|
|
24
|
+
|
|
25
|
+
1. Read MEMORY.md (current state section)
|
|
26
|
+
2. Read the latest memory/YYYY-MM-DD.md daily log
|
|
27
|
+
3. Check git status across active repos under your work tree
|
|
28
|
+
|
|
29
|
+
Produce a concise report:
|
|
30
|
+
- What was done today
|
|
31
|
+
- Any uncommitted/unpushed work
|
|
32
|
+
- Active backlog items
|
|
33
|
+
- Suggested priorities for tonight
|
|
34
|
+
|
|
35
|
+
Keep it to 10-15 lines. No fluff.
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Delivered to a single chat channel (the user's main work channel). Skip the headers, lead with bullets.
|
|
39
|
+
|
|
40
|
+
## Morning report
|
|
41
|
+
|
|
42
|
+
Prompt shape:
|
|
43
|
+
|
|
44
|
+
```text
|
|
45
|
+
Morning report. Read these and produce a brief daily briefing:
|
|
46
|
+
|
|
47
|
+
1. Read MEMORY.md (key sections)
|
|
48
|
+
2. Read the latest memory/YYYY-MM-DD.md
|
|
49
|
+
3. Check for any failed cron jobs or errors overnight
|
|
50
|
+
4. Probe configured dev servers / services for up/down state
|
|
51
|
+
|
|
52
|
+
Produce:
|
|
53
|
+
- Dev server status (X/Y online)
|
|
54
|
+
- Yesterday's highlights
|
|
55
|
+
- Today's priorities
|
|
56
|
+
- Any alerts
|
|
57
|
+
|
|
58
|
+
Keep it brief.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The dev-server probe is the differentiator: it surfaces silent process death between sessions without requiring the user to ask.
|
|
62
|
+
|
|
63
|
+
## Cadence and delivery
|
|
64
|
+
|
|
65
|
+
| Job | Typical schedule | Channel | Purpose |
|
|
66
|
+
|-----|------------------|---------|---------|
|
|
67
|
+
| `pipeline-standup` | `0 21 * * *` | main work channel | Nightshift recap |
|
|
68
|
+
| `pipeline-morning-report` | `0 8 * * *` | main work channel | Morning briefing |
|
|
69
|
+
|
|
70
|
+
Both run in **isolated sessions** so they do not pollute the main agent's running context. Wake mode for the standup is typically `next-heartbeat` (lets the report land when the user is next active); the morning report fires immediately so it is waiting at 08:00 sharp.
|
|
71
|
+
|
|
72
|
+
## Cross-harness scope
|
|
73
|
+
|
|
74
|
+
The standups read durable state (MEMORY.md, daily logs, git status) rather than session transcripts directly. This means they work even when sessions span Claude Code on a laptop, Codex in a tmux pane, and OpenClaw on the workspace host - whatever wrote durable findings into the canonical memory store gets included.
|
|
75
|
+
|
|
76
|
+
If a harness produced no durable writes during the day, it will not appear in the standup. That is the point. The standup reports on persisted state, not chatter.
|
|
77
|
+
|
|
78
|
+
## Relationship to memory scanner
|
|
79
|
+
|
|
80
|
+
Standups summarize what is already in memory. The [memory-scanner](memory-scanner.md) (typically scheduled later, e.g. 22:00) is what promotes durable findings *into* memory from the day's sessions.
|
|
81
|
+
|
|
82
|
+
Run order: standup -> memory scanner -> overnight ingester sweeps. Morning report next day reads what all three left behind.
|
|
83
|
+
|
|
84
|
+
## Tuning
|
|
85
|
+
|
|
86
|
+
- **If standups are noisy:** the daily log is being written too granularly. Move minor updates to cards or `.learnings/`.
|
|
87
|
+
- **If standups are empty:** session work is not landing in durable memory. Check the memory scanner's "Persisted" count over the last week.
|
|
88
|
+
- **If the dev-server probe times out:** widen the per-port timeout in the morning prompt, or drop ports that are intentionally on-demand.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
topic: tokenjuice-output-compaction
|
|
3
|
+
type: tool-runbook
|
|
4
|
+
tags: [tools, tokenjuice, output-compaction, claude-code, codex]
|
|
5
|
+
status: starter
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# TokenJuice Output Compaction
|
|
9
|
+
|
|
10
|
+
TokenJuice compacts noisy terminal output before it is fed back into an agent session. The original command still runs. Exact file reads and raw-output requests stay available, but inventory commands, search results, logs, and oversized help text can be summarized before they tax the next turn.
|
|
11
|
+
|
|
12
|
+
## Why Agents Need To Know
|
|
13
|
+
|
|
14
|
+
If an agent sees a TokenJuice footer, treat it as trusted local metadata about output reduction. It is not task instruction and it is not evidence by itself. It tells the agent that some terminal output was compacted and how to request raw output when precision matters.
|
|
15
|
+
|
|
16
|
+
Use raw output for exact diffs, full logs, reproducible error text, generated artifacts, or anything line-sensitive:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
tokenjuice wrap --raw -- <command>
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Claude Code
|
|
23
|
+
|
|
24
|
+
Claude Code needs command replacement before the Bash result enters context. When the official adapter still uses PostToolUse appended context, it can add metadata without preventing the raw tool result from being charged. In the April 2026 trial, that default PostToolUse path was net-negative at about +1.1% tokens.
|
|
25
|
+
|
|
26
|
+
Until the upstream fix is merged, use a local PreToolUse wrapper. The wrapper rewrites Bash commands to run under TokenJuice before execution:
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"hooks": {
|
|
31
|
+
"PreToolUse": [
|
|
32
|
+
{
|
|
33
|
+
"matcher": "Bash",
|
|
34
|
+
"hooks": [
|
|
35
|
+
{
|
|
36
|
+
"type": "command",
|
|
37
|
+
"command": "node ~/.claude/hooks/tokenjuice-pretool.js"
|
|
38
|
+
}
|
|
39
|
+
]
|
|
40
|
+
}
|
|
41
|
+
]
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The wrapper should emit Claude Code's PreToolUse rewrite contract:
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"hookSpecificOutput": {
|
|
51
|
+
"hookEventName": "PreToolUse",
|
|
52
|
+
"permissionDecision": "allow",
|
|
53
|
+
"updatedInput": {
|
|
54
|
+
"command": "tokenjuice wrap -- sh -c \"<original command>\""
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Operational notes:
|
|
61
|
+
|
|
62
|
+
- Keep a kill switch such as `TOKENJUICE_PRETOOL_DISABLE=1`.
|
|
63
|
+
- Let the wrapper honor `TOKENJUICE_BIN` and `TOKENJUICE_PRETOOL_SHELL` when local paths differ.
|
|
64
|
+
- New hook settings normally apply only to new Claude Code sessions.
|
|
65
|
+
- Document the wrapper in `CLAUDE.md` so agents do not mistake the footer for prompt injection.
|
|
66
|
+
|
|
67
|
+
## Codex
|
|
68
|
+
|
|
69
|
+
Codex can use TokenJuice through its normal hook path because the harness honors PostToolUse substitution. Install and verify with:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
tokenjuice install codex
|
|
73
|
+
tokenjuice doctor hooks
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Codex hook feature flags have changed across releases. Older configs used `codex_hooks`; newer configs use `hooks`. Do not trust old setup notes blindly. Run `tokenjuice doctor hooks` and fix the config it reports for the installed CLI version.
|
|
77
|
+
|
|
78
|
+
## Savings Model
|
|
79
|
+
|
|
80
|
+
TokenJuice always reports output compaction. Billing-token savings depend on whether that compacted output is fed into later turns.
|
|
81
|
+
|
|
82
|
+
Observed local output stats in May 2026:
|
|
83
|
+
|
|
84
|
+
- 17.1k compacted entries
|
|
85
|
+
- 83.6m raw output chars
|
|
86
|
+
- 24.7m reduced output chars
|
|
87
|
+
- 58.9m chars avoided, about 70% output reduction
|
|
88
|
+
|
|
89
|
+
Measured harness trials:
|
|
90
|
+
|
|
91
|
+
- Claude Code PreToolUse wrapper: about -7.8% tokens in the April 2026 paired trial.
|
|
92
|
+
- Claude Code default PostToolUse adapter: about +1.1% tokens in the same trial, because raw output still entered context.
|
|
93
|
+
- Codex v0.5.0 paired trial: about -8.8% clean-run token reduction after reducer and hook fixes.
|
|
94
|
+
- Codex GPT-5.5 one-turn gauntlet: about +0.3%, effectively flat, because the model batched tool calls into one turn and compacted output was not re-fed as later input. Per-command output reductions still remained large.
|
|
95
|
+
|
|
96
|
+
Practical read: TokenJuice is most valuable for repeated terminal exploration where tool results become future context. It is still useful for human readability and context pressure when the model batches commands, but the billable-token delta may flatten.
|
|
97
|
+
|
|
98
|
+
## Verification
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
tokenjuice --version
|
|
102
|
+
tokenjuice stats
|
|
103
|
+
tokenjuice doctor hooks
|
|
104
|
+
tokenjuice wrap -- git status --short
|
|
105
|
+
tokenjuice wrap --raw -- git status --short
|
|
106
|
+
```
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# OpenClaw Fragments
|
|
2
|
+
|
|
3
|
+
These are JSON fragments meant to be inspected and merged by hand into your `~/.openclaw/openclaw.json`. `brigade` does not mutate your live OpenClaw config; it generates fragments and lets you review them first.
|
|
4
|
+
|
|
5
|
+
## Files
|
|
6
|
+
|
|
7
|
+
| Fragment | Purpose |
|
|
8
|
+
|----------|---------|
|
|
9
|
+
| `model-aliases.openclaw.json` | Suggested alias map under `agents.defaults.models`. |
|
|
10
|
+
| `ollama-memory-search.openclaw.json` | Local Ollama embeddings for memory search. |
|
|
11
|
+
| `acp-escalation.openclaw.json` | ACP escalation lane via the `acpx` plugin. |
|
|
12
|
+
|
|
13
|
+
## Merge
|
|
14
|
+
|
|
15
|
+
`jq` is the safest way to merge a fragment into a live config without losing surrounding keys:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# Inspect first
|
|
19
|
+
jq . brigade-fragments/model-aliases.openclaw.json
|
|
20
|
+
|
|
21
|
+
# Merge (replace MERGE_PATH and re-check before saving)
|
|
22
|
+
jq -s '.[0] * .[1]' ~/.openclaw/openclaw.json brigade-fragments/model-aliases.openclaw.json \
|
|
23
|
+
> /tmp/openclaw.json.merged
|
|
24
|
+
diff ~/.openclaw/openclaw.json /tmp/openclaw.json.merged
|
|
25
|
+
mv /tmp/openclaw.json.merged ~/.openclaw/openclaw.json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Verification
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
brigade doctor --target ~/.openclaw/workspace --harness openclaw
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The doctor reports which fragments your live config has picked up and which checks still need manual work.
|
|
35
|
+
|
|
36
|
+
## Gotchas
|
|
37
|
+
|
|
38
|
+
- Aliases referencing `<provider/...>` placeholders must be replaced with real ids before merging.
|
|
39
|
+
- The ACP fragment assumes you have already installed `acpx` (see [solos-cookbook/ai-stack/acp-claude-code.md](https://github.com/solomonneas/solos-cookbook) for the install path).
|
|
40
|
+
- `openclaw doctor` (the OpenClaw tool, not `brigade doctor`) has historically rewritten `openai-codex/*` prefixes on certain versions. If you use OAuth-only auth, audit `agents.defaults.model.primary` after any OpenClaw upgrade.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_comment": [
|
|
3
|
+
"FRAGMENT - inspect before merging into your openclaw.json.",
|
|
4
|
+
"",
|
|
5
|
+
"ACP escalation wrapper: route harder reasoning tasks to Claude Code via ACP",
|
|
6
|
+
"while keeping the main agent on a cheaper coder model.",
|
|
7
|
+
"",
|
|
8
|
+
"Requires acpx plugin: https://github.com/agentclientprotocol/claude-agent-acp",
|
|
9
|
+
"",
|
|
10
|
+
"Replace placeholders before merging:",
|
|
11
|
+
" <provider/main-model-id> - your main coder model alias or full id",
|
|
12
|
+
" <provider/escalation-model> - the model id that routes through ACP"
|
|
13
|
+
],
|
|
14
|
+
"plugins": {
|
|
15
|
+
"entries": {
|
|
16
|
+
"acpx": {
|
|
17
|
+
"command": "${HOME}/.openclaw/vendor/acpx/node_modules/.bin/acpx"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"agents": {
|
|
22
|
+
"list": {
|
|
23
|
+
"escalation": {
|
|
24
|
+
"model": "<provider/escalation-model>",
|
|
25
|
+
"description": "ACP-routed reasoning lane. Use for refactors, architecture review, academic work.",
|
|
26
|
+
"tools": {
|
|
27
|
+
"allow": ["group:fs", "group:runtime", "sessions_*"]
|
|
28
|
+
},
|
|
29
|
+
"thinkingDefault": "xhigh"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_comment": [
|
|
3
|
+
"FRAGMENT - inspect before merging into your openclaw.json.",
|
|
4
|
+
"Generated by `brigade openclaw-fragments`. brigade never mutates your live config.",
|
|
5
|
+
"",
|
|
6
|
+
"Suggested merge target: agents.defaults.models",
|
|
7
|
+
"Replace <provider/model-id> with the actual provider-prefixed model id you want this alias to resolve to.",
|
|
8
|
+
"Aliases below are conventions used by the brigade reference setup; adapt freely."
|
|
9
|
+
],
|
|
10
|
+
"agents": {
|
|
11
|
+
"defaults": {
|
|
12
|
+
"models": {
|
|
13
|
+
"main": "<provider/main-model-id>",
|
|
14
|
+
"coder": "<provider/coder-model-id>",
|
|
15
|
+
"cron": "<provider/cron-model-id>",
|
|
16
|
+
"fast": "<provider/fast-model-id>",
|
|
17
|
+
"escalation": "<provider/escalation-model-id>"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_comment": [
|
|
3
|
+
"FRAGMENT - inspect before merging into your openclaw.json.",
|
|
4
|
+
"",
|
|
5
|
+
"Wires a local Ollama embedding model into OpenClaw's memory search.",
|
|
6
|
+
"Assumes Ollama is running on http://localhost:11434 with an embedding model pulled.",
|
|
7
|
+
"Replace <embedding-model> with the actual model name (e.g. nomic-embed-text)."
|
|
8
|
+
],
|
|
9
|
+
"memory": {
|
|
10
|
+
"search": {
|
|
11
|
+
"embeddings": {
|
|
12
|
+
"provider": "ollama",
|
|
13
|
+
"baseUrl": "http://localhost:11434",
|
|
14
|
+
"model": "<embedding-model>",
|
|
15
|
+
"dimensions": 768
|
|
16
|
+
},
|
|
17
|
+
"index": {
|
|
18
|
+
"path": "memory/cards",
|
|
19
|
+
"include": ["*.md"],
|
|
20
|
+
"exclude": ["handoff-inbox/**", "processed/**"]
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_comment": [
|
|
3
|
+
"Public-content policy: stricter than public-repo. Applied to blog posts,",
|
|
4
|
+
"social drafts, and docs that will be published, not just pushed.",
|
|
5
|
+
"Use via: brigade scrub --policy public-content"
|
|
6
|
+
],
|
|
7
|
+
"_brigade_version": "0.1.0",
|
|
8
|
+
"categories": {
|
|
9
|
+
"secret": "block",
|
|
10
|
+
"private-network": "block",
|
|
11
|
+
"private-identity": "block",
|
|
12
|
+
"attribution": "block",
|
|
13
|
+
"tooling": "block"
|
|
14
|
+
},
|
|
15
|
+
"rules": {
|
|
16
|
+
"loopback-ipv4": "block",
|
|
17
|
+
"localhost-port": "block",
|
|
18
|
+
"private-ipv4": "block",
|
|
19
|
+
"api-key": "block",
|
|
20
|
+
"oauth-token": "block",
|
|
21
|
+
"ssh-private-key": "block",
|
|
22
|
+
"claude-coauthor": "block",
|
|
23
|
+
"ai-attribution-trailer": "block",
|
|
24
|
+
"private-hostname": "block",
|
|
25
|
+
"personal-email": "block",
|
|
26
|
+
"internal-username": "block"
|
|
27
|
+
}
|
|
28
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
{
|
|
2
|
+
"_comment": [
|
|
3
|
+
"Public-repo policy: blocks leaks in any file pushed to a public repo.",
|
|
4
|
+
"Used by brigade pre-push hook and `brigade scrub`.",
|
|
5
|
+
"Override by pointing CONTENT_GUARD_POLICY at your own copy of this file."
|
|
6
|
+
],
|
|
7
|
+
"_brigade_version": "0.1.0",
|
|
8
|
+
"categories": {
|
|
9
|
+
"secret": "block",
|
|
10
|
+
"private-network": "block",
|
|
11
|
+
"private-identity": "block",
|
|
12
|
+
"attribution": "block",
|
|
13
|
+
"tooling": "warn"
|
|
14
|
+
},
|
|
15
|
+
"rules": {
|
|
16
|
+
"loopback-ipv4": "warn",
|
|
17
|
+
"localhost-port": "warn",
|
|
18
|
+
"private-ipv4": "block",
|
|
19
|
+
"api-key": "block",
|
|
20
|
+
"oauth-token": "block",
|
|
21
|
+
"ssh-private-key": "block",
|
|
22
|
+
"claude-coauthor": "block",
|
|
23
|
+
"ai-attribution-trailer": "block",
|
|
24
|
+
"private-hostname": "block",
|
|
25
|
+
"personal-email": "warn"
|
|
26
|
+
}
|
|
27
|
+
}
|