DEPRECATED (removal target: v3.0.0) — Use

ao lookup --query "topic"

for on-demand learnings retrieval, or see

.agents/AGENTS.md

for knowledge navigation. This skill and the

ao inject

CLI command still work but are no longer called from hooks or other skills.

Inject Skill

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

Inject relevant prior knowledge into the current session. Treat

$inject

How It Works

In the default

manual

$inject

ao inject

In

lean

legacy

AGENTOPS_STARTUP_CONTEXT_MODE

# 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 searches for relevant knowledge and injects it into context.

Work-Scoped Injection

When

--bead

HOOK_BEAD

• 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

• 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 inject --context "<topic>" --format markdown --max-tokens 1000

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

Knowledge Sources

~/.agents/MEMORY.md

.agents/learnings/

.agents/patterns/

~/.agents/learnings/

~/.agents/patterns/

.agents/research/

.agents/learnings/

~/.codex/patterns/

Decay Model

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

Key Rules

• Runs automatically - usually via hook
• Context-aware - filters by current directory/topic
• Token-budgeted - respects max-tokens limit
• Recency-weighted - newer knowledge prioritized

Examples

SessionStart Hook Invocation (lean/legacy modes only)

Hook triggers:

session-start.sh

AGENTOPS_STARTUP_CONTEXT_MODE=lean

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, research automatically available at session start without manual lookup.

Note: In the default

manual

ao search

ao lookup

Manual Context Injection

User says:

$inject authentication

What happens:

1. Agent calls

   ao inject --context "authentication" --format markdown --max-tokens 1000

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

$post-mortem

--context "<topic>"

--max-tokens

--apply-decay

Local Resources

scripts/

• scripts/validate.sh