inject

name: inject description: "Run inject."

DEPRECATED (removal target: v3.0.0) — Use ao lookup --query "topic" for on-demand learnings retrieval and phase-scoped context packets. This skill and the ao inject CLI command still work as compatibility adapters, but they are not the canonical context path and are not called from default hooks or other skills.

Inject Skill

Install & refresh (absorbed from using-agentops, ag-s43tg)

To update installed skills: re-run the install one-liner — bash <(curl -fsSL https://raw.githubusercontent.com/boshu2/agentops/main/scripts/install.sh). (There is no update skill; skill refresh is an install-script concern.)

On-demand knowledge retrieval. Not run automatically at startup (since ag-8km).

Codex orchestration note (absorbed from using-agentops, ag-s43tg): Codex skill orchestration default is $skill chaining. Chain skills as $skill invocations rather than shelling out to wrapper CLIs.

Load relevant prior knowledge into the current session as a legacy adapter. Treat $inject as passive compatibility lookup, not as a task-planning or task-execution entrypoint.

Lease

How It Works

In the default hookless startup path, no startup injection occurs. Run ao session bootstrap for the standard orientation report, then prefer ao lookup / ao inject for on-demand retrieval and bounded per-phase packets. Use $inject or ao inject only for legacy compatibility.

If you author an opt-in SessionStart hook or run a legacy hook profile, it may call:

# lean mode (MEMORY.md fresh): 400 tokens
ao inject --apply-decay --format markdown --max-tokens 400 \
  [--bead <bead-id>] [--predecessor <handoff-path>]

# legacy mode: 800 tokens
ao inject --apply-decay --format markdown --max-tokens 800 \
  [--bead <bead-id>] [--predecessor <handoff-path>]

This legacy path searches for relevant knowledge and prints a bounded summary.

Work-Scoped Injection

When --bead is provided (via HOOK_BEAD env var from Gas Town):

• Learnings tagged with the same bead ID get a 1.5x score boost
• Learnings matching bead labels get a 1.2x boost
• Untagged learnings still appear but ranked lower

Predecessor Context

When --predecessor is provided (path to a handoff file):

• Extracts structured context: progress, blockers, next steps
• Injected as "Predecessor Context" section before learnings
• Supports explicit handoffs, auto-handoffs, and pre-compact snapshots

Manual Execution

Given $inject [topic]:

Step 1: Search for Relevant Knowledge

With ao CLI:

ao lookup --query "<topic>" --limit 5

Without ao CLI, search manually:

# Global operating memory
sed -n '1,120p' ~/.agents/MEMORY.md 2>/dev/null

# Recent learnings
ls -lt .agents/learnings/ | head -5

# Recent patterns
ls -lt .agents/patterns/ | head -5

# Recent research
ls -lt .agents/research/ | head -5

# Global learnings (cross-repo knowledge)
ls -lt ~/.agents/learnings/ 2>/dev/null | head -5

# Global patterns (cross-repo patterns)
ls -lt ~/.agents/patterns/ 2>/dev/null | head -5

# Legacy patterns (read-only fallback, no new writes)
ls -lt ~/.codex/patterns/ 2>/dev/null | head -5

Step 2: Read Relevant Files

Read the most relevant artifacts based on topic.

Step 3: Summarize for Context

Present the injected knowledge:

• Global principles or constraints that apply everywhere
• Key learnings relevant to current work
• Patterns that may apply
• Recent research on related topics

Step 4: Record Citations (Feedback Loop)

After presenting injected knowledge, record which files were injected for the feedback loop:

mkdir -p .agents/ao
# Record each injected learning file as a citation
for injected_file in <list of files that were read and presented>; do
  echo "{\"artifact_path\": \"$injected_file\", \"cited_at\": \"$(date -Iseconds)\", \"session_id\": \"$(date +%Y-%m-%d)\", \"workspace_path\": \"$PWD\"}" >> .agents/ao/citations.jsonl
done

Citation tracking enables the feedback loop: learnings that are frequently cited get confidence boosts during $post-mortem, while uncited learnings decay faster.

Knowledge Sources

Decay Model

Knowledge relevance decays over time (~17%/week). More recent learnings are weighted higher.

Key Rules

• Does not run automatically - default context delivery is explicit
• Context-aware - filters by current directory/topic
• Token-budgeted - respects max-tokens limit
• Recency-weighted - newer knowledge prioritized

Examples

Opt-In Hook Profile Invocation (legacy only)

Hook trigger: an externally authored or legacy session-start.sh may run at session start with AGENTOPS_STARTUP_CONTEXT_MODE=lean or legacy

What happens:

1. Hook calls ao inject --apply-decay --format markdown --max-tokens 400 (lean) or --max-tokens 800 (legacy)
2. CLI searches .agents/learnings/, .agents/patterns/, .agents/research/ for relevant artifacts
3. CLI applies recency-weighted decay (~17%/week) to rank results
4. CLI outputs top-ranked knowledge as markdown within token budget
5. Agent presents injected knowledge in session context

Result: Prior learnings, patterns, and research are available for legacy hook profiles. This is not the default AgentOps 3.0 path.

Note: In the default hookless path, run ao session bootstrap and then pull context explicitly with ao lookup or ao inject.

Manual Context Injection

User says: $inject authentication or "recall knowledge about auth"

What happens:

1. Agent calls ao lookup --query "authentication" --limit 5
2. CLI filters artifacts by topic relevance
3. Agent reads top-ranked learnings and patterns
4. Agent summarizes injected knowledge for current work
5. Agent references artifact paths for deeper exploration

Result: Topic-specific knowledge retrieved and summarized, enabling faster context loading than full artifact reads.

Troubleshooting

Local Resources

scripts/

• scripts/validate.sh