Proposal: update specification — document real retrieval algorithms for all 6 ACMS built-in context strategies #6194

New issue

Open

opened 2026-04-09 17:34:11 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 17:34:11 +00:00

Owner

Proposal: Update Specification — ACMS Built-in Strategy Real Retrieval Algorithms

What Changed in the Implementation

Merged PR #3635 (fix(acms): implement real retrieval logic in all 6 spec-required context strategies, merged 2026-04-05) replaced all 6 no-op stub implementations in the ACMS built-in context strategy classes with real backend-driven retrieval logic.

Merged PR #3682 (docs: document ACMS real retrieval logic and automatic checkpoint triggers, merged 2026-04-05) added reference documentation for these strategies in docs/reference/context_strategies.md.

What Spec Sections Need Updating

The spec's §45477–45507 (Built-in Strategy Catalogue) describes the 6 strategies but does not document their actual retrieval algorithms. The implementation has now defined these concretely:

§45477 — Strategy: `simple-keyword`

Proposed addition: Documents that this strategy queries TextBackend.search() with keywords extracted from ContextRequest.query or ContextRequest.entities. Results are sorted by relevance score (descending) and packed greedily within the token budget via _budget_fragments(). Quality score: 0.3.

§45481 — Strategy: `semantic-embedding`

Proposed addition: Documents that this strategy queries VectorBackend.similarity_search() with a character-frequency embedding vector derived from the request query. In v1, the embedding is a bag-of-characters vector over ASCII ordinals 32–95, L2-normalised. Results sorted by cosine similarity, budget-packed. Quality score: 0.6. Note: v1 uses character-frequency approximation; production will use a real embedding model.

§45485 — Strategy: `breadth-depth-navigator`

Proposed addition: Documents that this strategy traverses GraphBackend from focus nodes specified in ContextRequest.focus, expanding outward by request.breadth hops. Each triple is converted to a ContextFragment. Falls back to SPARQL query when no focus nodes are specified. Quality score: 0.85.

§45489 — Strategy: `arce` (Autonomous Reasoning Context Extraction)

Proposed addition: Documents the multi-modal pipeline:

Text phase: 40% of budget → TextBackend.search()
Vector phase: 40% of budget → VectorBackend.similarity_search() with character-frequency embedding
Graph phase: 20% of budget → GraphBackend.traverse() from focus nodes (limited to 3 nodes, 10 triples each)
Results merged and deduplicated by UKO URI (higher-scored fragment wins)
Quality score: 0.95

§45499 — Strategy: `temporal-archaeology`

Proposed addition: Documents two-phase retrieval:

TemporalBackend.query_by_tier(tier=COLD, ...) for historical nodes
GraphBackend.traverse() from focus nodes (depth=1, up to 5 nodes, 5 triples each)

Historical nodes scored at quality_score * 0.7; current nodes at full quality_score
Quality score: 0.5

§45503 — Strategy: `plan-decision-context`

Proposed addition: Documents that this strategy queries TemporalBackend for nodes associated with parent and ancestor plan IDs from PlanContext. Parent plan decisions scored at full quality; ancestor decisions at quality_score * 0.8; historical (non-current) decisions at quality_score * 0.6. Falls back to warm-tier query when no parent/ancestor plans exist. Quality score: 0.7.

Internal Spec Contradiction to Resolve

The strategy_stubs.py code notes a contradiction between:

§25223: Lists 4 default-enabled strategies (including arce)
§28682: Lists 3 default-enabled strategies (without arce)

The implementation follows §28682 (3 strategies: simple-keyword, semantic-embedding, breadth-depth-navigator). The spec should be updated to resolve this contradiction — either remove arce from §25223's default list or add it to §28682.

Rationale

The implementation in PR #3635 defines the concrete retrieval algorithms for all 6 strategies. These are better than the spec's abstract descriptions — they provide specific backend interactions, budget allocation ratios, and fallback behaviors. The spec should document these concrete algorithms as the canonical implementation.

Scope

Spec sections affected:

§45477 — Strategy: simple-keyword
§45481 — Strategy: semantic-embedding
§45485 — Strategy: breadth-depth-navigator
§45489 — Strategy: arce
§45499 — Strategy: temporal-archaeology
§45503 — Strategy: plan-decision-context
§25223 — Built-in Strategies table (resolve contradiction with §28682)
§28682 — context.strategies.enabled config key default value

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Proposal: Update Specification — ACMS Built-in Strategy Real Retrieval Algorithms ### What Changed in the Implementation **Merged PR #3635** (`fix(acms): implement real retrieval logic in all 6 spec-required context strategies`, merged 2026-04-05) replaced all 6 no-op stub implementations in the ACMS built-in context strategy classes with real backend-driven retrieval logic. **Merged PR #3682** (`docs: document ACMS real retrieval logic and automatic checkpoint triggers`, merged 2026-04-05) added reference documentation for these strategies in `docs/reference/context_strategies.md`. ### What Spec Sections Need Updating The spec's §45477–45507 (Built-in Strategy Catalogue) describes the 6 strategies but does not document their actual retrieval algorithms. The implementation has now defined these concretely: #### §45477 — Strategy: `simple-keyword` **Proposed addition**: Documents that this strategy queries `TextBackend.search()` with keywords extracted from `ContextRequest.query` or `ContextRequest.entities`. Results are sorted by relevance score (descending) and packed greedily within the token budget via `_budget_fragments()`. Quality score: 0.3. #### §45481 — Strategy: `semantic-embedding` **Proposed addition**: Documents that this strategy queries `VectorBackend.similarity_search()` with a character-frequency embedding vector derived from the request query. In v1, the embedding is a bag-of-characters vector over ASCII ordinals 32–95, L2-normalised. Results sorted by cosine similarity, budget-packed. Quality score: 0.6. **Note**: v1 uses character-frequency approximation; production will use a real embedding model. #### §45485 — Strategy: `breadth-depth-navigator` **Proposed addition**: Documents that this strategy traverses `GraphBackend` from focus nodes specified in `ContextRequest.focus`, expanding outward by `request.breadth` hops. Each triple is converted to a `ContextFragment`. Falls back to SPARQL query when no focus nodes are specified. Quality score: 0.85. #### §45489 — Strategy: `arce` (Autonomous Reasoning Context Extraction) **Proposed addition**: Documents the multi-modal pipeline: - Text phase: 40% of budget → `TextBackend.search()` - Vector phase: 40% of budget → `VectorBackend.similarity_search()` with character-frequency embedding - Graph phase: 20% of budget → `GraphBackend.traverse()` from focus nodes (limited to 3 nodes, 10 triples each) - Results merged and deduplicated by UKO URI (higher-scored fragment wins) - Quality score: 0.95 #### §45499 — Strategy: `temporal-archaeology` **Proposed addition**: Documents two-phase retrieval: 1. `TemporalBackend.query_by_tier(tier=COLD, ...)` for historical nodes 2. `GraphBackend.traverse()` from focus nodes (depth=1, up to 5 nodes, 5 triples each) - Historical nodes scored at `quality_score * 0.7`; current nodes at full `quality_score` - Quality score: 0.5 #### §45503 — Strategy: `plan-decision-context` **Proposed addition**: Documents that this strategy queries `TemporalBackend` for nodes associated with parent and ancestor plan IDs from `PlanContext`. Parent plan decisions scored at full quality; ancestor decisions at `quality_score * 0.8`; historical (non-current) decisions at `quality_score * 0.6`. Falls back to warm-tier query when no parent/ancestor plans exist. Quality score: 0.7. ### Internal Spec Contradiction to Resolve The `strategy_stubs.py` code notes a contradiction between: - **§25223**: Lists 4 default-enabled strategies (including `arce`) - **§28682**: Lists 3 default-enabled strategies (without `arce`) The implementation follows §28682 (3 strategies: `simple-keyword`, `semantic-embedding`, `breadth-depth-navigator`). The spec should be updated to resolve this contradiction — either remove `arce` from §25223's default list or add it to §28682. ### Rationale The implementation in PR #3635 defines the concrete retrieval algorithms for all 6 strategies. These are **better than the spec's abstract descriptions** — they provide specific backend interactions, budget allocation ratios, and fallback behaviors. The spec should document these concrete algorithms as the canonical implementation. ### Scope Spec sections affected: - §45477 — Strategy: `simple-keyword` - §45481 — Strategy: `semantic-embedding` - §45485 — Strategy: `breadth-depth-navigator` - §45489 — Strategy: `arce` - §45499 — Strategy: `temporal-archaeology` - §45503 — Strategy: `plan-decision-context` - §25223 — Built-in Strategies table (resolve contradiction with §28682) - §28682 — `context.strategies.enabled` config key default value --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added the

labels

2026-04-09 17:34:26 +00:00

HAL9000 added this to the v3.4.0 milestone

2026-04-09 17:34:27 +00:00