mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
docs(context): sweep remaining ao inject references across docs/tests/scripts
Wave 3 of context-enforcement-phase3: replace ao inject workflow guidance with ao lookup across documentation, test fixtures, and scripts. Remaining 32 references are legitimate (inject command implementation, CHANGELOG history, CLI reference tables, test fixtures for command detection). Files updated: - 11 core docs (context-packet, seed-definition, leverage-points, etc.) - 7 workflow diagram docs (brief, system-map, cli-skills-map, HOOKS, etc.) - 4 scripts (proof-run, test-flywheel, check-skill-flag-refs, etc.) - 3 shell tests (proof-run e2e, token-budgets, no-compaction) - 1 Go test (json_validity_test.go) - Production code: metrics_nudge.go, metrics_flywheel.go, hooks.go
This commit is contained in:
Boden Fuller
@@ -60,10 +60,19 @@
|
||||
},
|
||||
{
|
||||
"name": "ao inject",
|
||||
"description": "Search and output relevant knowledge for session startup.",
|
||||
"description": "Deprecated: use ao lookup instead. Legacy command for session knowledge injection.",
|
||||
"usage": "ao inject [context] [flags]",
|
||||
"category": "knowledge",
|
||||
"flags": ["--context", "--format", "--max-tokens", "--no-cite"]
|
||||
"flags": ["--context", "--format", "--max-tokens", "--no-cite"],
|
||||
"deprecated": true,
|
||||
"replacement": "ao lookup"
|
||||
},
|
||||
{
|
||||
"name": "ao lookup",
|
||||
"description": "Search and retrieve relevant knowledge from the flywheel.",
|
||||
"usage": "ao lookup --query <query> [flags]",
|
||||
"category": "knowledge",
|
||||
"flags": ["--query", "--json", "--format", "--max-tokens", "--apply-decay"]
|
||||
},
|
||||
{
|
||||
"name": "ao ratchet",
|
||||
@@ -86,11 +95,11 @@
|
||||
"flags": ["--full", "--markdown", "--repo", "--since"]
|
||||
}
|
||||
],
|
||||
"total": 11,
|
||||
"total": 12,
|
||||
"categories": {
|
||||
"health": ["badge", "doctor", "status"],
|
||||
"setup": ["config", "hooks"],
|
||||
"knowledge": ["feedback", "forge", "inject"],
|
||||
"knowledge": ["feedback", "forge", "inject", "lookup"],
|
||||
"workflow": ["goals", "ratchet"],
|
||||
"validation": ["vibe-check"]
|
||||
}
|
||||
@@ -346,7 +355,7 @@
|
||||
"```bash",
|
||||
"ao status # Knowledge base state",
|
||||
"ao doctor # Health checks",
|
||||
"ao inject # Load prior knowledge",
|
||||
"ao lookup # Search prior knowledge",
|
||||
"ao badge # Flywheel health badge",
|
||||
"ao goals measure # Fitness check",
|
||||
"ao ratchet status # Workflow progress",
|
||||
|
||||
@@ -126,7 +126,7 @@ This is why AgentOps feels different in practice: the output is not just code. I
|
||||
|
||||
- **Execution system**: `/plan`, beads, worktrees, `/crank`, `/evolve`
|
||||
- **Validation system**: `/pre-mortem`, `/vibe`, `/council`
|
||||
- **Memory system**: `.agents/`, `ao inject`, `ao forge`, `/retro`, `/knowledge`
|
||||
- **Memory system**: `.agents/`, `ao lookup`, `ao forge`, `/retro`, `/knowledge`
|
||||
|
||||
That is the real architecture. Not just a skill pack. A local operating layer around the agent.
|
||||
|
||||
@@ -137,11 +137,11 @@ This is the compounding part, but now in mechanical terms. Your agent validates
|
||||
```text
|
||||
> /research "retry backoff strategies"
|
||||
|
||||
[inject] 3 prior learnings loaded (freshness-weighted):
|
||||
[lookup] 3 prior learnings found (freshness-weighted):
|
||||
- Token bucket with Redis (established, high confidence)
|
||||
- Rate limit at middleware layer, not per-handler (pattern)
|
||||
- /login endpoint was missing rate limiting (decision)
|
||||
[research] Found prior art in your codebase + injected context
|
||||
[research] Found prior art in your codebase + retrieved context
|
||||
Recommends: exponential backoff with jitter, reuse existing Redis client
|
||||
```
|
||||
|
||||
@@ -432,7 +432,7 @@ Session N ends
|
||||
→ ao feedback-loop: citation-to-utility feedback (MemRL)
|
||||
|
||||
Session N+1 starts
|
||||
→ ao inject (lean mode): score artifacts by recency + utility
|
||||
→ ao lookup (on demand): score artifacts by recency + utility
|
||||
├── Local .agents/ learnings & patterns (1.0x weight)
|
||||
├── Global ~/.agents/ cross-repo knowledge (0.8x weight)
|
||||
├── Work-scoped boost: active issue gets 1.5x (--bead)
|
||||
|
||||
+2
-3
@@ -61,9 +61,8 @@ ao hooks test # Verify hooks work
|
||||
## Knowledge Commands
|
||||
|
||||
```bash
|
||||
ao inject "kubernetes" # Inject knowledge about k8s
|
||||
ao inject --apply-decay # Apply confidence decay first
|
||||
ao search "error handling" # Search knowledge base
|
||||
ao lookup --query "kubernetes" # Look up knowledge about k8s
|
||||
ao search "error handling" # Search knowledge base
|
||||
```
|
||||
|
||||
## Task Integration
|
||||
|
||||
+1
-1
@@ -797,7 +797,7 @@ func printHooksInstallSummary(settingsPath string, newHooks *HooksConfig, events
|
||||
}
|
||||
} else {
|
||||
fmt.Println("Hooks installed:")
|
||||
fmt.Println(" SessionStart: ao extract + ao inject")
|
||||
fmt.Println(" SessionStart: ao extract + signpost pointer")
|
||||
fmt.Println(" SessionEnd: ao forge + ao maturity")
|
||||
fmt.Println(" Stop: ao flywheel close-loop")
|
||||
}
|
||||
|
||||
@@ -579,7 +579,7 @@ func TestJSONValidity_FlywheelNudge(t *testing.T) {
|
||||
LearningsCount: 10,
|
||||
PoolPending: 2,
|
||||
PoolApproaching: 1,
|
||||
Suggestion: "Run 'ao inject' to improve retrieval",
|
||||
Suggestion: "Run 'ao lookup' to improve retrieval",
|
||||
}
|
||||
|
||||
out := captureJSONStdout(t, func() {
|
||||
|
||||
@@ -154,7 +154,7 @@ func printFlywheelStatus(w io.Writer, m *types.FlywheelMetrics) {
|
||||
fmt.Fprintln(w)
|
||||
fmt.Fprintln(w, " RECOMMENDATIONS:")
|
||||
if m.Sigma < 0.3 {
|
||||
fmt.Fprintln(w, " • Improve retrieval: run 'ao inject' more often")
|
||||
fmt.Fprintln(w, " • Improve retrieval: use 'ao lookup' for on-demand knowledge")
|
||||
}
|
||||
if m.Rho < 0.5 {
|
||||
fmt.Fprintln(w, " • Cite more learnings: reference artifacts in your work")
|
||||
|
||||
@@ -220,7 +220,7 @@ func buildSuggestion(metrics *types.FlywheelMetrics, rpiState RPIState, poolPend
|
||||
// Priority 4: Flywheel health
|
||||
if !metrics.AboveEscapeVelocity {
|
||||
if metrics.Sigma < 0.3 {
|
||||
return "Improve retrieval: run 'ao inject' more often"
|
||||
return "Improve retrieval: use 'ao lookup' for on-demand knowledge"
|
||||
}
|
||||
if metrics.Rho < 0.5 {
|
||||
return "Cite more learnings: reference artifacts in your work"
|
||||
|
||||
@@ -152,7 +152,7 @@ func TestBuildSuggestion(t *testing.T) {
|
||||
rpiState: RPIState{},
|
||||
poolPending: 0,
|
||||
poolApproaching: 0,
|
||||
wantContains: "ao inject",
|
||||
wantContains: "ao lookup",
|
||||
},
|
||||
{
|
||||
name: "low rho",
|
||||
|
||||
+10
-11
@@ -23,9 +23,9 @@ When you start a Claude Code session, behavior depends on `AGENTOPS_STARTUP_CONT
|
||||
|
||||
**`manual` (default):** MEMORY.md is auto-loaded by Claude Code. The hook emits only a pointer to on-demand retrieval commands (`ao search`, `ao lookup`). No `ao extract` or `ao inject` runs. This is the lightest startup path.
|
||||
|
||||
**`lean`:** Runs `ao extract` + `ao inject` with a reduced token budget (400 tokens when MEMORY.md is fresh). Provides automatic knowledge injection alongside MEMORY.md. Use `AGENTOPS_STARTUP_LEGACY_INJECT=1` to force this mode.
|
||||
**`lean`:** Runs `ao extract` + `ao lookup` with a reduced token budget (400 tokens when MEMORY.md is fresh). Provides automatic knowledge retrieval alongside MEMORY.md. Use `AGENTOPS_STARTUP_LEGACY_INJECT=1` to force this mode.
|
||||
|
||||
**`legacy`:** Runs `ao extract` + `ao inject` with full token budget (800 tokens). Pre-notebook behavior for backward compatibility.
|
||||
**`legacy`:** Runs `ao extract` + `ao lookup` with full token budget (800 tokens). Pre-notebook behavior for backward compatibility.
|
||||
|
||||
In `lean`/`legacy` modes, injection is weighted by:
|
||||
- **Freshness**: More recent = higher score
|
||||
@@ -166,13 +166,13 @@ Note: this is a minimal example. `ao hooks install` is recommended for full cove
|
||||
Control what happens at session start via environment variable:
|
||||
|
||||
```bash
|
||||
# Default — extract + inject with reduced budget (lean injection alongside MEMORY.md)
|
||||
# Default — extract + lookup with reduced budget (lean retrieval alongside MEMORY.md)
|
||||
AGENTOPS_STARTUP_CONTEXT_MODE=lean claude
|
||||
|
||||
# MEMORY.md auto-loaded, no extract/inject (lightest)
|
||||
# MEMORY.md auto-loaded, no extract/lookup (lightest)
|
||||
AGENTOPS_STARTUP_CONTEXT_MODE=manual claude
|
||||
|
||||
# Full extract + inject (pre-notebook backward compatibility)
|
||||
# Full extract + lookup (pre-notebook backward compatibility)
|
||||
AGENTOPS_STARTUP_CONTEXT_MODE=legacy claude
|
||||
```
|
||||
|
||||
@@ -183,7 +183,6 @@ In `manual` mode, use CLI commands for on-demand knowledge retrieval:
|
||||
```bash
|
||||
ao search "authentication" # Search knowledge by keyword
|
||||
ao lookup --query "auth flow" # Relevance-ranked lookup
|
||||
ao inject --max-tokens 1000 # Manual knowledge injection
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
@@ -200,21 +199,21 @@ which ao
|
||||
export PATH="$HOME/go/bin:$PATH"
|
||||
```
|
||||
|
||||
### No knowledge being injected
|
||||
### No knowledge being retrieved
|
||||
|
||||
1. Check if `.agents/learnings/` exists and has content:
|
||||
```bash
|
||||
ls -la .agents/learnings/
|
||||
```
|
||||
|
||||
2. Verify inject works manually:
|
||||
2. Verify lookup works manually:
|
||||
```bash
|
||||
ao inject --verbose
|
||||
ao lookup --query "test" --verbose
|
||||
```
|
||||
|
||||
3. Check for parse errors:
|
||||
```bash
|
||||
ao inject 2>&1 | head -20
|
||||
ao lookup --query "test" 2>&1 | head -20
|
||||
```
|
||||
|
||||
### Hooks not running
|
||||
@@ -248,7 +247,7 @@ For deep dive: see `docs/the-science.md` in the repository.
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `ao inject` | Manually inject knowledge |
|
||||
| `ao lookup` | On-demand knowledge retrieval |
|
||||
| `ao forge transcript` | Extract learnings from transcripts |
|
||||
| `ao task-sync` | Sync Claude Code tasks to CASS |
|
||||
| `ao feedback-loop` | Update utility scores |
|
||||
|
||||
@@ -415,11 +415,10 @@ Three hooks form the knowledge flywheel's mechanical backbone:
|
||||
On session start, `hooks/session-start.sh`:
|
||||
1. Creates `.agents/` directories if missing (local + global `~/.agents/`)
|
||||
2. Runs `ao extract` to process any pending knowledge queue
|
||||
3. Runs `ao inject --apply-decay --max-tokens 1000` to load context:
|
||||
- **Local** `.agents/learnings/` and `.agents/patterns/` (1.0x weight)
|
||||
- **Global** `~/.agents/learnings/` and `~/.agents/patterns/` (0.8x weight, cross-repo)
|
||||
- **Work-scoped boost**: if `HOOK_BEAD` is set (active issue), matching learnings get 1.5x
|
||||
- **Predecessor context**: if `.agents/handoff/` contains a handoff, injects what the previous session was working on (~200 tokens)
|
||||
3. Points to `.agents/AGENTS.md` signpost for on-demand knowledge navigation:
|
||||
- **Local** `.agents/learnings/` and `.agents/patterns/` available via `ao lookup --query "topic"`
|
||||
- **Global** `~/.agents/learnings/` and `~/.agents/patterns/` (cross-repo, 0.8x weight in lookup scoring)
|
||||
- **Predecessor context**: if `.agents/handoff/` contains a handoff, emits what the previous session was working on (~200 tokens)
|
||||
- **Two-phase MemRL ranking**: Phase A scores by similarity + freshness, Phase B by utility + composite. Result: the most recent, most relevant learnings from *this repo* surface first
|
||||
4. Injects `using-agentops` skill content as context
|
||||
5. Outputs JSON with `additionalContext` for compatible agent runtimes
|
||||
|
||||
+1
-1
@@ -49,7 +49,7 @@ These control AO CLI configuration loading and RPI control-plane command customi
|
||||
| `AGENTOPS_RPI_AO_COMMAND` | `ao` | `ao` command used for ratchet/checkpoint operations in RPI control plane. |
|
||||
| `AGENTOPS_RPI_BD_COMMAND` | `bd` | `bd` command used for epic and child issue queries in RPI control plane. |
|
||||
| `AGENTOPS_RPI_TMUX_COMMAND` | `tmux` | `tmux` command used for status liveness probes in RPI control plane. |
|
||||
| `RPI_RUN_ID` | (unset) | When set, `ao inject --for=<skill>` uses this as the context artifact directory name instead of generating an `adhoc-<timestamp>` ID. Automatically set by the `/rpi` orchestrator during phased runs. |
|
||||
| `RPI_RUN_ID` | (unset) | When set, `ao lookup --for=<skill>` uses this as the context artifact directory name instead of generating an `adhoc-<timestamp>` ID. Automatically set by the `/rpi` orchestrator during phased runs. |
|
||||
|
||||
## Hooks
|
||||
|
||||
|
||||
+2
-2
@@ -35,7 +35,7 @@ metadata:
|
||||
|
||||
### `context`
|
||||
|
||||
Controls what knowledge `ao inject --for=<skill>` provides. Two forms:
|
||||
Controls what knowledge `ao lookup --for=<skill>` provides. Two forms:
|
||||
|
||||
**String form** (backward compat):
|
||||
```yaml
|
||||
@@ -85,7 +85,7 @@ Valid section names:
|
||||
| `INTEL` | Learnings and patterns from the knowledge flywheel |
|
||||
| `TASK` | Current bead ID and predecessor context |
|
||||
|
||||
**v1 status:** Actively enforced at runtime. `ao inject --for=<skill>` zeroes excluded/non-included sections.
|
||||
**v1 status:** Actively enforced at runtime. `ao lookup --for=<skill>` zeroes excluded/non-included sections.
|
||||
|
||||
#### `context.intent.mode`
|
||||
|
||||
|
||||
@@ -149,7 +149,7 @@ AgentOps applies the same insight one layer up. Not better AI models. Better fee
|
||||
```
|
||||
SKILL ao CLI COMMAND RESULT
|
||||
───── ────────────── ──────
|
||||
/research → ao inject Prior knowledge loaded
|
||||
/research → ao lookup Prior knowledge loaded
|
||||
/retro → ao forge transcript Learnings extracted
|
||||
/retro → ao pool promote Learnings validated
|
||||
/evolve → ao goals measure Fitness checked
|
||||
@@ -180,7 +180,7 @@ KNOWLEDGE FLYWHEEL VALIDATION GATES SESSION / LIFECYCLE
|
||||
ao forge ao gate pending ao session close
|
||||
ao pool ingest ao gate approve ao rpi status
|
||||
ao pool promote ao gate reject ao hooks list
|
||||
ao inject ao ratchet status ao config
|
||||
ao lookup ao ratchet status ao config
|
||||
ao lookup ao ratchet record
|
||||
ao search ao ratchet check METRICS / HEALTH
|
||||
ao dedup ────────────────
|
||||
|
||||
@@ -79,7 +79,7 @@ Skills hand off to `ao` to persist knowledge across sessions:
|
||||
```
|
||||
SKILL ao CLI COMMAND RESULT
|
||||
───── ────────────── ──────
|
||||
/research → ao inject Prior knowledge loaded into session
|
||||
/research → ao lookup Prior knowledge loaded into session
|
||||
/retro → ao forge transcript Learnings extracted from session
|
||||
/retro → ao pool promote Validated learnings promoted
|
||||
/evolve → ao goals measure Fitness checked before next cycle
|
||||
@@ -97,7 +97,7 @@ KNOWLEDGE FLYWHEEL VALIDATION GATES SESSION / LIFECYCLE
|
||||
ao forge ao gate pending ao session close
|
||||
ao pool ingest ao gate approve ao rpi status
|
||||
ao pool promote ao gate reject ao rpi cancel
|
||||
ao inject ao ratchet status ao hooks list
|
||||
ao lookup ao ratchet status ao hooks list
|
||||
ao lookup ao ratchet record ao config
|
||||
ao search ao ratchet check
|
||||
ao dedup ao ratchet promote METRICS / HEALTH
|
||||
|
||||
+18
-21
@@ -12,7 +12,7 @@ schema_version: 1
|
||||
|
||||
## Overview
|
||||
|
||||
A context packet is the structured payload assembled by `ao inject` and delivered into an agent's context window at session start. It replaces the current raw knowledge dump with a purpose-built artifact containing exactly what an agent needs to do its work — no more, no less.
|
||||
A context packet is the structured payload assembled by `ao lookup` and delivered into an agent's context window on demand. It replaces the current raw knowledge dump with a purpose-built artifact containing exactly what an agent needs to do its work — no more, no less.
|
||||
|
||||
The packet has five sections, each with a defined character budget, content source, and eviction priority. The total budget is ~28K characters (~7K tokens at `InjectCharsPerToken = 4`), which leaves 90%+ of the context window available for actual work.
|
||||
|
||||
@@ -150,7 +150,7 @@ Future sessions will see what you did and how it went.
|
||||
```
|
||||
|
||||
**Assembly rules:**
|
||||
1. The `--context` query (or positional argument to `ao inject`) filters learnings and patterns by substring match against the agent's task description.
|
||||
1. The `--query` argument (to `ao lookup`) filters learnings and patterns by substring match against the agent's task description.
|
||||
2. Learnings are ranked by composite score (freshness * utility, Two-Phase MemRL retrieval). Maximum 10 learnings.
|
||||
3. Patterns are ranked by composite score. Maximum 5 patterns.
|
||||
4. Olympus constraints are included unfiltered (they are always relevant as hard boundaries).
|
||||
@@ -280,7 +280,7 @@ Commit your work with clear messages. Write a session summary to
|
||||
| PROTOCOL | 200 | 2,000 | 2,500 | ~500 |
|
||||
| **Total** | **1,000** | **28,000** | **35,500** | **~7,000** |
|
||||
|
||||
Token estimates use `InjectCharsPerToken = 4` (conservative, from `cli/cmd/ao/inject.go:22`).
|
||||
Token estimates use `InjectCharsPerToken = 4` (conservative, from `cli/cmd/ao/lookup.go`).
|
||||
|
||||
### Overflow Eviction Order
|
||||
|
||||
@@ -346,9 +346,9 @@ Before assembly, each section's raw content passes through a redaction gate. The
|
||||
The complete assembly flow from invocation to output:
|
||||
|
||||
```
|
||||
ao inject [--context="<query>"] [--max-tokens=N]
|
||||
ao lookup [--query="<query>"] [--max-tokens=N]
|
||||
│
|
||||
├─ 1. Resolve query (positional arg or --context flag)
|
||||
├─ 1. Resolve query (--query flag)
|
||||
│
|
||||
├─ 2. Gather raw content for each section:
|
||||
│ ├─ GOALS: goals.LoadGoals() + latest snapshot
|
||||
@@ -420,24 +420,21 @@ This provenance record enables:
|
||||
|
||||
---
|
||||
|
||||
## Evolution of `ao inject`
|
||||
## Evolution of `ao lookup`
|
||||
|
||||
The current `ao inject` (as of `inject.go`) outputs a flat knowledge dump: learnings, patterns, sessions, and OL constraints rendered as markdown or JSON. The context packet evolves this in three phases:
|
||||
The deprecated `ao inject` output a flat knowledge dump: learnings, patterns, sessions, and OL constraints rendered as markdown or JSON. The context packet evolves this through an on-demand retrieval pattern:
|
||||
|
||||
### Phase 1: Structured Sections (non-breaking)
|
||||
|
||||
Add `--packet` flag to `ao inject`. When set, output is organized into the five sections defined above instead of the current flat format. Without `--packet`, behavior is unchanged.
|
||||
`ao lookup` organizes output into the five sections defined above instead of the legacy flat format.
|
||||
|
||||
```bash
|
||||
# Current (unchanged):
|
||||
ao inject "authentication"
|
||||
|
||||
# New:
|
||||
ao inject --packet "authentication"
|
||||
ao inject --packet --max-tokens 7000 "authentication"
|
||||
# On-demand query:
|
||||
ao lookup --query "authentication"
|
||||
ao lookup --query "authentication" --max-tokens 7000
|
||||
```
|
||||
|
||||
The `--packet` flag activates:
|
||||
`ao lookup` activates:
|
||||
- Section-based assembly instead of flat rendering
|
||||
- Per-section char budgets and overflow eviction
|
||||
- Redaction gate before assembly
|
||||
@@ -450,12 +447,12 @@ Wire the GOALS and TASK sections into the packet assembler:
|
||||
- TASK: accept a `--task` flag or `--bead` flag that pulls the bead description.
|
||||
|
||||
```bash
|
||||
ao inject --packet --bead ag-poz.2 "authentication"
|
||||
ao lookup --query "authentication" --bead ag-poz.2
|
||||
```
|
||||
|
||||
### Phase 3: Default Packet Mode
|
||||
### Phase 3: On-Demand Default
|
||||
|
||||
Once validated in production, `--packet` becomes the default. The old flat format is available via `--legacy`. The session-start hook (`hooks/session-start.sh`) is updated to call `ao inject --packet` instead of `ao inject`.
|
||||
The on-demand pattern (`ao lookup`) replaces the session-start injection model. Agents consult `.agents/AGENTS.md` for orientation and use `ao lookup --query "topic"` to retrieve context when needed.
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
@@ -491,7 +488,7 @@ The context packet unifies and structures what multiple components already provi
|
||||
|
||||
| Component | Current Role | Context Packet Role |
|
||||
|-----------|-------------|---------------------|
|
||||
| `ao inject` (`inject.go`) | Flat knowledge dump | Becomes the packet assembler |
|
||||
| `ao lookup` (`lookup.go`) | On-demand knowledge retrieval | The packet assembler |
|
||||
| `goals.LoadGoals()` | Fitness measurement | Feeds GOALS section |
|
||||
| `collectLearnings()` | MemRL retrieval | Feeds INTEL section (learnings) |
|
||||
| `collectPatterns()` | Pattern retrieval | Feeds INTEL section (patterns) |
|
||||
@@ -499,7 +496,7 @@ The context packet unifies and structures what multiple components already provi
|
||||
| `collectRecentSessions()` | Session history | Feeds HISTORY section (sessions) |
|
||||
| `ratchet.LoadChain()` | Provenance chain | Feeds HISTORY section (chain) |
|
||||
| `recordCitations()` | Citation tracking | Provenance tracking (injection-log.jsonl) |
|
||||
| `hooks/session-start.sh` | Session initialization | Calls `ao inject --packet` |
|
||||
| `hooks/session-start.sh` | Session initialization | Points agent to `.agents/AGENTS.md` for on-demand lookup |
|
||||
| Memory packets (`memory-packet.v1.schema.json`) | Boundary-memory for handoff | Orthogonal — handoff packets are emitted at session END; context packets are assembled at session START |
|
||||
|
||||
---
|
||||
@@ -510,5 +507,5 @@ The context packet unifies and structures what multiple components already provi
|
||||
- [Knowledge Flywheel](knowledge-flywheel.md) — How learnings compound across sessions
|
||||
- [How It Works](how-it-works.md) — Context windowing, Brownian Ratchet, Ralph Wiggum
|
||||
- [The Science](the-science.md) — Freshness decay model, MemRL two-phase retrieval
|
||||
- [CLI Reference](../cli/docs/COMMANDS.md) — `ao inject` command documentation
|
||||
- [CLI Reference](../cli/docs/COMMANDS.md) — `ao lookup` command documentation
|
||||
- [OL-AO Bridge Contracts](ol-bridge-contracts.md) — Olympus constraint interchange
|
||||
|
||||
@@ -47,7 +47,7 @@ v1 (ship first) v2 (after v1 proves out) v3 (after v2 proves out)
|
||||
|
||||
**v1 closes the biggest gap.** Today, `/forge` and `/retro` produce unstructured markdown files that go directly into `.agents/learnings/` with no verification. v1 adds structure (typed artifacts) and mechanical truth checks (did the tests pass?). This alone prevents the most damaging failure mode: confidently wrong learnings entering the knowledge base.
|
||||
|
||||
**v2 adds discoverability and quality measurement.** Once artifacts are structured and verified, they can be tagged for retrieval and scored for quality. This makes `ao search` and `ao inject` return better results and enables the pool tiering system (gold/silver/bronze) to operate on verified data.
|
||||
**v2 adds discoverability and quality measurement.** Once artifacts are structured and verified, they can be tagged for retrieval and scored for quality. This makes `ao search` and `ao lookup` return better results and enables the pool tiering system (gold/silver/bronze) to operate on verified data.
|
||||
|
||||
**v3 adds the feedback loop.** Once artifacts are scored, the system can reject low-quality or stale knowledge and compile high-quality knowledge into permanent defenses. This is where the system starts to exhibit self-organization: it generates its own constraints from its own experience.
|
||||
|
||||
@@ -183,7 +183,7 @@ Depends on **CATALOG** -- can only verify artifacts that have been cataloged wit
|
||||
|
||||
## Stage 3: INDEX
|
||||
|
||||
**What it does:** Tags cataloged, verified artifacts by topic, skill, and goal. Makes them findable through `ao search` and surfaceable through `ao inject`.
|
||||
**What it does:** Tags cataloged, verified artifacts by topic, skill, and goal. Makes them findable through `ao search` and surfaceable through `ao lookup`.
|
||||
|
||||
### Input
|
||||
|
||||
@@ -218,7 +218,7 @@ Additionally, a JSONL entry is appended to `.agents/ao/search-index.jsonl`:
|
||||
### Connection to Existing Infrastructure
|
||||
|
||||
- **Search:** Enriches `ao search` results. Currently, search scans markdown files and JSONL session logs. INDEX adds structured topic/keyword metadata that improves relevance ranking.
|
||||
- **Inject:** Improves `ao inject --context "<topic>"` filtering. Currently, inject uses substring matching against file content. INDEX adds explicit topic tags for faster, more accurate filtering.
|
||||
- **Lookup:** Improves `ao lookup --query "<topic>"` filtering. Currently, lookup uses substring matching against file content. INDEX adds explicit topic tags for faster, more accurate filtering.
|
||||
- **Forge:** `ao forge markdown` already writes to `search-index.jsonl`. INDEX extends this with richer metadata.
|
||||
- **CLI:** `ao curate index` -- reads cataloged entries, extracts topics/keywords, updates search index.
|
||||
|
||||
@@ -226,7 +226,7 @@ Additionally, a JSONL entry is appended to `.agents/ao/search-index.jsonl`:
|
||||
|
||||
| Failure | Impact | Mitigation |
|
||||
|---------|--------|------------|
|
||||
| INDEX missing | Artifacts are stored but not findable. `ao search` returns results based only on content grep. `ao inject` loads by recency only, not relevance. | This is today's status quo. INDEX improves retrieval quality but its absence doesn't break anything. |
|
||||
| INDEX missing | Artifacts are stored but not findable. `ao search` returns results based only on content grep. `ao lookup` loads by recency only, not relevance. | This is today's status quo. INDEX improves retrieval quality but its absence doesn't break anything. |
|
||||
| Wrong topics assigned | Artifact tagged with irrelevant topics. Returns as noise in search results. | INDEX runs after VERIFY, so at minimum the content is mechanically validated. Topic assignment can be re-run (`ao curate index --reindex`). |
|
||||
| Index drift | Search index diverges from actual pool state (entries deleted but index not updated). | Index is append-only JSONL. `ao search` validates entries exist before returning results. Periodic `ao curate index --rebuild` reconciles. |
|
||||
|
||||
@@ -469,9 +469,9 @@ The pipeline degrades gracefully. Each version is strictly better than the previ
|
||||
|
||||
| State | What Works | What's Missing | Net Effect |
|
||||
|-------|-----------|----------------|------------|
|
||||
| **No pipeline** (today) | `/forge` and `/retro` write markdown to `.agents/`. `ao inject` loads by recency. `ao search` greps content. | No structure, no verification, no quality filtering, no expiry, no constraints. | Raw accumulation. Knowledge base grows but quality is random. |
|
||||
| **No pipeline** (today) | `/forge` and `/retro` write markdown to `.agents/`. `ao lookup` loads by recency. `ao search` greps content. | No structure, no verification, no quality filtering, no expiry, no constraints. | Raw accumulation. Knowledge base grows but quality is random. |
|
||||
| **v1: CATALOG + VERIFY** | Artifacts are typed (learning/decision/failure/pattern). Mechanical verification (tests passed? goals improved?). | No topic tagging, no quality scoring, no rejection, no constraints. | Structured accumulation. Wrong learnings caught by test verification. Already a major improvement: the single biggest risk (confidently wrong learnings) is mitigated. |
|
||||
| **v2: + INDEX + SCORE** | Artifacts are findable by topic. Quality-gated into tiers. Search returns ranked results. Inject loads best-quality first. | No automated rejection, no constraint compilation. | Quality-filtered retrieval. Token budget spent on high-quality learnings first. Noise reduced proportional to scoring accuracy. |
|
||||
| **v2: + INDEX + SCORE** | Artifacts are findable by topic. Quality-gated into tiers. Search returns ranked results. Lookup loads best-quality first. | No automated rejection, no constraint compilation. | Quality-filtered retrieval. Token budget spent on high-quality learnings first. Noise reduced proportional to scoring accuracy. |
|
||||
| **v3: + REJECT + CONSTRAIN** | Stale/wrong learnings removed. High-quality learnings compiled into hooks. Full feedback loop. | Manual constraint activation. | Self-organizing system. Generates its own defenses from experience. Unlearns what no longer applies. The flywheel equation has all terms active. |
|
||||
|
||||
**v1 alone closes the biggest gap.** The jump from "no pipeline" to "v1" is larger than any subsequent jump. Structured, verified artifacts are dramatically better than unstructured, unverified markdown -- even without scoring or rejection.
|
||||
@@ -509,7 +509,7 @@ The pipeline degrades gracefully. Each version is strictly better than the previ
|
||||
│ STAGE 3: INDEX │ v2
|
||||
│ Tag by topic, skill, │
|
||||
│ goal. Update search idx │
|
||||
│ → ao search, ao inject │
|
||||
│ → ao search, ao lookup │
|
||||
└────────────┬─────────────┘
|
||||
│
|
||||
▼
|
||||
@@ -575,5 +575,5 @@ When the schema evolves, the version increments. Readers check the version and a
|
||||
- `ao pool list` -- View pool entries by tier and status
|
||||
- `ao feedback` -- Record MemRL reward signals
|
||||
- `ao search` -- Search knowledge base (improved by INDEX)
|
||||
- `ao inject` -- Load prior knowledge (improved by INDEX + SCORE)
|
||||
- `ao lookup` -- Query prior knowledge on demand (improved by INDEX + SCORE)
|
||||
- `ao flywheel status` -- Knowledge growth rate and escape velocity
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
| Summary budget | 500 tokens | Briefing packet assembly (`ao context assemble`) |
|
||||
| Max waves per epic | 50 | `/crank` FIRE loop global limit |
|
||||
| Max retries per gate | 3 | Gate retry logic in validation hooks |
|
||||
| Confidence decay | 10%/week | Learning freshness scoring in `ao inject` |
|
||||
| Confidence decay | 10%/week | Learning freshness scoring in `ao lookup` |
|
||||
| Circuit breaker | 60 minutes | `/evolve` stops if no productive cycle in 60 min |
|
||||
|
||||
**dK/dt mapping:** These tune `delta`, `phi`, and the operating bounds of `sigma`. Changing them shifts the curve; it does not change the shape of the system.
|
||||
@@ -72,7 +72,7 @@ The knowledge stock `K` lives in `.agents/`. Its structure:
|
||||
**Flows:**
|
||||
- **Inflow:** `ao forge` (session learnings), `/retro`, `/post-mortem` deposit into `I(t)`
|
||||
- **Outflow (decay):** `ao maturity --expire` removes stale artifacts, freshness scoring deprioritizes old knowledge
|
||||
- **Reinforcement:** `ao inject` retrieves from stock, citation tracking records usage, MemRL utility scoring adjusts future retrieval priority
|
||||
- **Reinforcement:** `ao lookup` retrieves from stock on demand, citation tracking records usage, MemRL utility scoring adjusts future retrieval priority
|
||||
- **Friction:** As `K` grows, retrieval quality degrades without active scale controls (tiering, pruning, re-indexing)
|
||||
|
||||
**dK/dt mapping:** This IS the physical equation. `K` = `.agents/` corpus. `I(t)` = forge inflow. `delta * K` = expiry outflow. `sigma * rho * K` = retrieval-citation compounding. `phi * K^2` = scale friction.
|
||||
@@ -107,7 +107,7 @@ The knowledge stock `K` lives in `.agents/`. Its structure:
|
||||
|
||||
| Loop | Mechanism | What it balances | Files/commands |
|
||||
|------|-----------|------------------|----------------|
|
||||
| **B1: Freshness decay** | Knowledge decays at ~17%/week without retrieval | Prevents stale knowledge from polluting decisions | `ao maturity --expire`, freshness scoring in `ao inject` |
|
||||
| **B1: Freshness decay** | Knowledge decays at ~17%/week without retrieval | Prevents stale knowledge from polluting decisions | `ao maturity --expire`, freshness scoring in `ao lookup` |
|
||||
| **B2: Scale friction** | As K grows, retrieval quality degrades and governance cost rises | Prevents corpus bloat from collapsing sigma | Tiering, pruning, MemRL utility scoring (`ao feedback`) |
|
||||
| **Regression gates** | `/evolve` snapshots fitness before each cycle; regression = automatic revert | Prevents improvement cycles from making things worse | `ao goals measure`, fitness snapshot comparison |
|
||||
| **Council FAIL** | Multi-model council returns FAIL verdict; blocks merge | Prevents bad code from locking into ratchet | `/vibe`, `/council` verdicts in `.agents/council/` |
|
||||
@@ -134,7 +134,7 @@ The knowledge stock `K` lives in `.agents/`. Its structure:
|
||||
**R1: The Knowledge Flywheel**
|
||||
|
||||
```
|
||||
retrieve (ao inject)
|
||||
retrieve (ao lookup --query "topic")
|
||||
|
|
||||
v
|
||||
use in session (citation)
|
||||
@@ -148,7 +148,7 @@ better future retrieval (higher utility scores)
|
||||
+---> ao forge extracts new learnings
|
||||
| |
|
||||
v v
|
||||
retrieve (ao inject) ... [loop repeats]
|
||||
retrieve (ao lookup) ... [loop repeats]
|
||||
```
|
||||
|
||||
This is the `sigma * rho * K` compounding term. Each retrieval-and-use cycle:
|
||||
@@ -181,7 +181,7 @@ When `dominant: "R1"`, the flywheel is spinning faster than decay can drain it.
|
||||
|
||||
| Flow | From | To | Mechanism | Why it matters |
|
||||
|------|------|----|-----------|----------------|
|
||||
| Knowledge injection | `.agents/learnings/` | Session context | `ao inject` (freshness-weighted, utility-scored) | Session N knows what session 1 learned |
|
||||
| Knowledge injection | `.agents/learnings/` | Session context | `ao lookup` (freshness-weighted, utility-scored, on demand) | Session N knows what session 1 learned |
|
||||
| Knowledge extraction | Session output | `.agents/learnings/` | `ao forge` (hook-enforced at session end) | Experience survives session death |
|
||||
| Briefing packets | Prior research/plans | Agent context | `ao context assemble` (500-token summaries) | Right information, right phase, right agent |
|
||||
| Least-privilege loading | Full knowledge stock | Filtered subset | Phase-based and role-based filtering | Prevents lost-in-the-middle; context as security boundary |
|
||||
@@ -193,7 +193,7 @@ When `dominant: "R1"`, the flywheel is spinning faster than decay can drain it.
|
||||
|
||||
**dK/dt mapping:** Directly increases `sigma` by getting the right knowledge to the right window at the right time. Also increases `rho` by making retrieved knowledge more relevant to the current task (phase scoping reduces noise).
|
||||
|
||||
**Status:** Implemented. All seven information flows are active. `ao context assemble` and `ao inject` are the primary delivery mechanisms.
|
||||
**Status:** Implemented. All seven information flows are active. `ao context assemble` and `ao lookup` are the primary delivery mechanisms.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -155,7 +155,7 @@ OL `harvestCandidate` maps to AO `Candidate` as follows:
|
||||
|
||||
### File Format
|
||||
|
||||
OL harvest outputs markdown with YAML frontmatter to `.agents/learnings/`. AO `inject` discovers files at this same path.
|
||||
OL harvest outputs markdown with YAML frontmatter to `.agents/learnings/`. AO discovers files at this same path (see `.agents/AGENTS.md` for knowledge layout).
|
||||
|
||||
**Transport note:** The file system under `.agents/` is the canonical transport for this profile, but the contract surface is still `INVOCATION_ENVELOPE` (this is not an extra bridge surface).
|
||||
|
||||
@@ -284,8 +284,8 @@ Rather than version parsing, use feature detection:
|
||||
# Check if ol harvest supports --format flag
|
||||
ol harvest --help 2>&1 | grep -q "\-\-format" && OL_HAS_FORMAT=true
|
||||
|
||||
# Check if ao inject supports --ol-constraints flag
|
||||
ao inject --help 2>&1 | grep -q "ol-constraints" && AO_HAS_OL=true
|
||||
# Check if ao lookup supports --ol-constraints flag
|
||||
ao lookup --help 2>&1 | grep -q "ol-constraints" && AO_HAS_OL=true
|
||||
|
||||
# Check if ol validate stage1 exists
|
||||
ol validate stage1 --help 2>/dev/null && OL_HAS_STAGE1=true
|
||||
@@ -298,7 +298,7 @@ ol validate stage1 --help 2>/dev/null && OL_HAS_STAGE1=true
|
||||
| `ol` not on PATH | Skip OL integration, pure AO mode |
|
||||
| `ao` not on PATH | Skip AO integration, pure OL mode |
|
||||
| `ol harvest --format=ao` not supported | Manual file copy from `.agents/learnings/` |
|
||||
| `ao inject --ol-constraints` not supported | Skip constraint injection |
|
||||
| `ao lookup --ol-constraints` not supported | Skip constraint injection |
|
||||
| `.ol/` directory missing | Not an Olympus project, skip all OL features |
|
||||
|
||||
### 3.5 MemRL Policy Migration
|
||||
|
||||
@@ -55,7 +55,7 @@ An append-only ledger with cache-like semantics. Nothing gets overwritten. Every
|
||||
ao/ -- session index, provenance, metrics
|
||||
```
|
||||
|
||||
**Why it exists:** The flywheel needs a place to write. Without `.agents/`, `ao forge` has nowhere to put learnings, `ao inject` has nothing to retrieve, and knowledge dies with each session. This is the physical `K` stock from the equation.
|
||||
**Why it exists:** The flywheel needs a place to write. Without `.agents/`, `ao forge` has nowhere to put learnings, `ao lookup` has nothing to retrieve, and knowledge dies with each session. This is the physical `K` stock from the equation.
|
||||
|
||||
**Meadows mapping:** #10 (material stocks), #7 (reinforcing feedback loop -- more knowledge enables better retrieval enables more knowledge).
|
||||
|
||||
@@ -65,11 +65,11 @@ Hooks that fire on session lifecycle events. The minimum viable set:
|
||||
|
||||
| Event | Hook | What it does |
|
||||
|-------|------|--------------|
|
||||
| SessionStart | session-start | Inject top learnings, clean stale state |
|
||||
| SessionStart | session-start | Load context signpost (`.agents/AGENTS.md`), clean stale state |
|
||||
| SessionEnd | session-end | Extract learnings (`ao forge`), expire stale artifacts |
|
||||
| Stop | stop | Close the feedback loop (`ao flywheel close-loop`) |
|
||||
|
||||
**Why it exists:** Hooks are Meadows #5 -- structural rules. Without hooks, knowledge extraction depends on the agent remembering to run `ao forge`. Agents forget. Hooks do not. The flywheel only turns automatically if hooks enforce the extract-inject cycle.
|
||||
**Why it exists:** Hooks are Meadows #5 -- structural rules. Without hooks, knowledge extraction depends on the agent remembering to run `ao forge`. Agents forget. Hooks do not. The flywheel only turns automatically if hooks enforce the extract-and-retrieve cycle.
|
||||
|
||||
**Meadows mapping:** #5 (rules), #6 (information flows -- hooks ensure knowledge moves from session output to persistent storage to next session input).
|
||||
|
||||
@@ -79,7 +79,7 @@ Two lines added to the repo's CLAUDE.md:
|
||||
|
||||
```markdown
|
||||
## Knowledge Flywheel
|
||||
Run `ao inject` at session start. Run `ao forge` at session end.
|
||||
See `.agents/AGENTS.md` for orientation. Run `ao lookup --query "topic"` when you need prior knowledge. Run `ao forge` at session end.
|
||||
```
|
||||
|
||||
**Why it exists:** Hooks handle the automation, but CLAUDE.md provides the fallback for environments where hooks are not configured and the explanation for environments where they are. It bridges the gap between "hooks fire automatically" and "the agent understands why." This is belt-and-suspenders: structural enforcement (hooks) plus cognitive priming (instructions).
|
||||
@@ -116,7 +116,7 @@ This repo was seeded on DATE with goals: GOAL_1, GOAL_2, GOAL_3.
|
||||
Initial state: SUMMARY. Run /evolve to begin improvement.
|
||||
```
|
||||
|
||||
**Why it exists:** A flywheel with zero learnings is a flywheel that has never turned. The bootstrap learning ensures `ao inject` has something to retrieve on the very first session. It primes the reinforcing loop (Meadows #7) so the system starts compounding immediately instead of running one empty cycle first.
|
||||
**Why it exists:** A flywheel with zero learnings is a flywheel that has never turned. The bootstrap learning ensures `ao lookup` has something to retrieve on the very first session. It primes the reinforcing loop (Meadows #7) so the system starts compounding immediately instead of running one empty cycle first.
|
||||
|
||||
**Meadows mapping:** #7 (reinforcing feedback -- the initial push that starts the flywheel turning).
|
||||
|
||||
|
||||
@@ -41,7 +41,7 @@ dK/dt = I(t) - d*K + s*r*K - f*K^2
|
||||
| `K` | Knowledge stock (validated learnings, patterns, decisions) | `.agents/` corpus |
|
||||
| `I(t)` | Input rate (new knowledge per cycle) | `ao forge`, `/retro`, `/post-mortem` |
|
||||
| `d` | Decay rate (~17%/week without reinforcement, Darr 1995) | `ao maturity --expire` |
|
||||
| `s` | Retrieval effectiveness (do you find what you need?) | `ao inject` freshness-weighted scoring, `ao search` |
|
||||
| `s` | Retrieval effectiveness (do you find what you need?) | `ao lookup` freshness-weighted scoring, `ao search` |
|
||||
| `r` | Citation rate (do you use what you find?) | Knowledge reuse in research/plan phases |
|
||||
| `f` | Scale friction (indexing overhead, noise, governance cost) | Tiering, pruning, utility scoring (MemRL) |
|
||||
|
||||
@@ -63,7 +63,7 @@ Donella Meadows ranked intervention points in complex systems from least to most
|
||||
| 9 | Delays | Freshness decay intervals, maturity lifecycle (expire/evict), stale run TTL | Controls lag between `I(t)` and usable `K` |
|
||||
| 8 | Balancing feedback loops | Regression gates auto-revert bad cycles, council FAIL blocks merge, push gate blocks unvalidated code | Prevents `K` regression |
|
||||
| 7 | Reinforcing feedback loops | Knowledge flywheel (session N learnings feed session N+1), citation-based utility scoring (MemRL) | The `s*r*K` compounding term |
|
||||
| 6 | Information flows | `ao inject` (knowledge into context), `ao forge` (experience out of sessions), hook nudges, briefing packets | Increases `s` by getting right knowledge to right window |
|
||||
| 6 | Information flows | `ao lookup` (knowledge into context on demand), `ao forge` (experience out of sessions), hook nudges, briefing packets | Increases `s` by getting right knowledge to right window |
|
||||
| 5 | Rules | Hooks (3 active lifecycle events in `hooks/hooks.json`), validation gates, worker-guard (lead-only commit), dangerous-git guard, pre-mortem gate | Structural enforcement. Rules cannot be forgotten or ignored. |
|
||||
| 4 | Self-organization | `/evolve` fitness loop (measure-fix-validate-learn-repeat), constraint compiler (learnings become structural rules), progressive skill revelation | The system improves its own rules based on experience |
|
||||
| 3 | Goals | `GOALS.md` with mechanically verifiable gates, `ao goals measure`, severity-weighted selection, North Stars and Anti Stars | System intent. What the system optimizes toward. |
|
||||
@@ -101,7 +101,7 @@ AgentOps: 12 hook lifecycle events that fire automatically on session start, too
|
||||
### 5. From "knowledge is hoarded" to "knowledge is flowing" (Flywheel)
|
||||
|
||||
Traditional: knowledge lives in individual context windows and dies when the session ends.
|
||||
AgentOps: knowledge is extracted (`ao forge`), quality-gated (specificity, actionability, novelty scoring), tiered (gold/silver/bronze), freshness-decayed, and re-injected at the next session start (`ao inject`). The flywheel makes session 50 know what session 1 learned. Knowledge that is not retrieved and used decays. Knowledge that compounds survives.
|
||||
AgentOps: knowledge is extracted (`ao forge`), quality-gated (specificity, actionability, novelty scoring), tiered (gold/silver/bronze), freshness-decayed, and retrieved on demand (`ao lookup`). The flywheel makes session 50 know what session 1 learned. Knowledge that is not retrieved and used decays. Knowledge that compounds survives.
|
||||
|
||||
### 6. From "designed systems" to "evolved systems" (The Seed)
|
||||
|
||||
|
||||
@@ -121,7 +121,7 @@ echo ""
|
||||
# We look for lines containing `ao <subcommand> ... --<flag>`
|
||||
# This captures patterns like:
|
||||
# ao goals measure --json
|
||||
# ao inject --apply-decay --format markdown
|
||||
# ao lookup --apply-decay --format markdown
|
||||
# ao ratchet record implement --output "<path>"
|
||||
# ao rpi cleanup --all --prune-worktrees
|
||||
#
|
||||
|
||||
@@ -19,17 +19,17 @@ source_bead: proof-test
|
||||
source_phase: validate
|
||||
---
|
||||
# Proof Run Learning
|
||||
When testing flywheel compounding, always verify inject retrieves prior session learnings.
|
||||
When testing flywheel compounding, always verify lookup retrieves prior session learnings.
|
||||
LEARNING
|
||||
|
||||
# Session 2: Verify inject retrieves it
|
||||
RESULT=$(cd "$TEST_DIR" && ao inject "flywheel compounding" --format json --no-cite 2>/dev/null) || {
|
||||
echo "FAIL: ao inject command failed"
|
||||
# Session 2: Verify lookup retrieves it
|
||||
RESULT=$(cd "$TEST_DIR" && ao lookup --query "flywheel compounding" --json 2>/dev/null) || {
|
||||
echo "FAIL: ao lookup command failed"
|
||||
exit 1
|
||||
}
|
||||
|
||||
COUNT=$(echo "$RESULT" | jq '.learnings | length' 2>/dev/null) || {
|
||||
echo "FAIL: Could not parse inject output as JSON"
|
||||
echo "FAIL: Could not parse lookup output as JSON"
|
||||
echo "Raw output: $RESULT"
|
||||
exit 1
|
||||
}
|
||||
@@ -42,8 +42,8 @@ else
|
||||
fi
|
||||
|
||||
# Session 3: Verify scoring is operational (with decay)
|
||||
RESULT2=$(cd "$TEST_DIR" && ao inject "flywheel compounding" --apply-decay --format json --no-cite 2>/dev/null) || {
|
||||
echo "FAIL: ao inject --apply-decay command failed"
|
||||
RESULT2=$(cd "$TEST_DIR" && ao lookup --query "flywheel compounding" --apply-decay --json 2>/dev/null) || {
|
||||
echo "FAIL: ao lookup --apply-decay command failed"
|
||||
exit 1
|
||||
}
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
set -euo pipefail
|
||||
|
||||
# Flywheel Smoke Test
|
||||
# Verifies the knowledge flywheel (forge transcript → forge markdown → inject) works end-to-end
|
||||
# Verifies the knowledge flywheel (forge transcript → forge markdown → lookup) works end-to-end
|
||||
|
||||
TEST_DIR="$(mktemp -d)"
|
||||
AGENTS_DIR="${TEST_DIR}/.agents"
|
||||
@@ -19,8 +19,8 @@ echo ""
|
||||
# Setup test .agents structure
|
||||
mkdir -p "$AGENTS_DIR"/{learnings,patterns,ao/pending,ao/index}
|
||||
|
||||
# Test 1: Inject can read learnings
|
||||
echo "--- Test 1: Inject reads learnings ---"
|
||||
# Test 1: Lookup can read learnings
|
||||
echo "--- Test 1: Lookup reads learnings ---"
|
||||
cat > "$AGENTS_DIR/learnings/test-smoke.md" << 'EOF'
|
||||
# Test Learning: Flywheel Smoke Test
|
||||
|
||||
@@ -61,13 +61,13 @@ fi
|
||||
# With ao CLI available, run full test
|
||||
cd "$TEST_DIR"
|
||||
|
||||
# Test inject reads the learning
|
||||
INJECT_OUTPUT=$(ao inject --format markdown --max-tokens 500 2>&1 || true)
|
||||
# Test lookup reads the learning
|
||||
LOOKUP_OUTPUT=$(ao lookup --query "flywheel" --format markdown --max-tokens 500 2>&1 || true)
|
||||
|
||||
if echo "$INJECT_OUTPUT" | grep -q "Flywheel Smoke Test"; then
|
||||
echo "✓ Inject found test learning"
|
||||
if echo "$LOOKUP_OUTPUT" | grep -q "Flywheel Smoke Test"; then
|
||||
echo "✓ Lookup found test learning"
|
||||
else
|
||||
echo "⚠️ Inject didn't find learning (may be empty without prior sessions)"
|
||||
echo "⚠️ Lookup didn't find learning (may be empty without prior sessions)"
|
||||
fi
|
||||
|
||||
# Test 2: Forge transcript can process last session
|
||||
@@ -99,6 +99,6 @@ echo "=== Smoke Test PASSED ==="
|
||||
echo ""
|
||||
echo "Flywheel components verified:"
|
||||
echo " - .agents/learnings/ structure ✓"
|
||||
echo " - ao inject command ✓"
|
||||
echo " - ao lookup command ✓"
|
||||
echo " - ao forge transcript --last-session --quiet command ✓"
|
||||
echo " - ao forge markdown command ✓"
|
||||
|
||||
@@ -145,7 +145,7 @@ if [[ $total_fail -gt 0 ]]; then
|
||||
echo "Remediation:"
|
||||
echo " 1. Check skill SKILL.md sizes — move content to references/"
|
||||
echo " 2. Check hook output — reduce SessionStart injection volume"
|
||||
echo " 3. Check ao inject --max-tokens limit (currently 1000)"
|
||||
echo " 3. Check ao lookup / signpost token budget (session injection volume)"
|
||||
echo " 4. Review log files in $LOG_DIR for details"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
#
|
||||
# Demonstrates 3-session compounding of the AgentOps knowledge flywheel:
|
||||
# Session 1: Discovery — research + learn → learnings created
|
||||
# Session 2: Compound — inject → learnings surfaced and applied
|
||||
# Session 3: Mature — inject again → maturation visible
|
||||
# Session 2: Compound — lookup/signpost → learnings surfaced and applied
|
||||
# Session 3: Mature — lookup/signpost again → maturation visible
|
||||
#
|
||||
# Fully automated, no interactive prompts, CI-runnable.
|
||||
# Exit 0 = proof passes. Exit 1 = proof fails (with reason).
|
||||
@@ -202,8 +202,8 @@ log "Session 1: complete. Learnings on disk: $LEARNING_COUNT"
|
||||
log ""
|
||||
log "==================================================================="
|
||||
log "SESSION 2: Compounding"
|
||||
log " Simulate 'ao inject' loading learnings from Session 1."
|
||||
log " Assert: injection surfaces prior learnings."
|
||||
log " Simulate knowledge lookup loading learnings from Session 1."
|
||||
log " Assert: lookup surfaces prior learnings."
|
||||
log " Assert: output references prior learning content."
|
||||
log "==================================================================="
|
||||
|
||||
@@ -280,7 +280,7 @@ log "Session 2: complete. Learnings on disk: $LEARNING_COUNT2"
|
||||
log ""
|
||||
log "==================================================================="
|
||||
log "SESSION 3: Maturation"
|
||||
log " Simulate continued injection and knowledge compounding."
|
||||
log " Simulate continued lookup and knowledge compounding."
|
||||
log " Assert: maturation is visible (retrieval_count, new builds-on)."
|
||||
log " Assert: new learnings reference prior session learnings."
|
||||
log "==================================================================="
|
||||
|
||||
@@ -105,11 +105,11 @@ hook_tokens=$(estimate_tokens $HOOK_WRAPPER_BYTES)
|
||||
echo " Hook wrapper overhead: ${hook_tokens} tokens (${HOOK_WRAPPER_BYTES} bytes, estimated)"
|
||||
session_total_bytes=$((session_total_bytes + HOOK_WRAPPER_BYTES))
|
||||
|
||||
# Component 3: ao inject cap (default --max-tokens 1000 = ~4000 bytes)
|
||||
AO_INJECT_BYTES=4000
|
||||
inject_tokens=$(estimate_tokens $AO_INJECT_BYTES)
|
||||
echo " ao inject cap: ${inject_tokens} tokens (${AO_INJECT_BYTES} bytes, estimated)"
|
||||
session_total_bytes=$((session_total_bytes + AO_INJECT_BYTES))
|
||||
# Component 3: ao lookup / signpost cap (default budget ~4000 bytes)
|
||||
AO_LOOKUP_BYTES=4000
|
||||
lookup_tokens=$(estimate_tokens $AO_LOOKUP_BYTES)
|
||||
echo " ao lookup/signpost cap: ${lookup_tokens} tokens (${AO_LOOKUP_BYTES} bytes, estimated)"
|
||||
session_total_bytes=$((session_total_bytes + AO_LOOKUP_BYTES))
|
||||
|
||||
session_total_tokens=$(estimate_tokens $session_total_bytes)
|
||||
echo ""
|
||||
@@ -141,7 +141,7 @@ if [[ $failed -gt 0 ]]; then
|
||||
echo "Remediation:"
|
||||
echo " 1. Move content from SKILL.md to references/ (loaded JIT)"
|
||||
echo " 2. Check SessionStart hook output volume"
|
||||
echo " 3. Reduce ao inject --max-tokens limit"
|
||||
echo " 3. Reduce ao lookup / signpost token budget"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
|
||||
Reference in New Issue
Block a user