docs: agentmemory parity audit — promises, requirements, principles + ROADMAP split - #202
Merged
Merged
Conversation
Resolves four DROPPED-UNINTENTIONAL items from the agentmemory parity audit: - exploration / Thompson-sampling decision (REQ-010): documents that the absence of bandit-style exploration on top of posterior reranking is intentional, not an oversight; exploration breaks determinism. - 2,000-token budget calibration (REQ-004): notes the default is the inherited research-line calibration against full-dump baselines, re-measured at the v2.0 reproducibility cut. - enforcement-tier honest decomposition (REQ-027): imports the research-line tier-table framing — Tiers 1-3 hold mechanically, Tiers 4-5 are deferred, Tier 6 (LLM compliance) is not under aelfrice's control. - session-recovery promise distinct from write durability (REQ-005): ties the README 'where were we?' claim to a verifiable property separate from SQLite WAL durability. - confidence-drift auto-flag absence (design-principle #18): notes that posterior drops below 0.5 do not surface a flag at v1.x; only locked-belief demotion-pressure produces a visible state change.
Resolves four DROPPED-UNINTENTIONAL items from the agentmemory parity
audit, all in LIMITATIONS:
- Onboarding scope: extends the AST-language gap line to also call
out the missing extractor *kinds* (citation-ref, test-impl linkage,
directive detection) that the research line shipped; ties the
directive detector to the deferred enforcement tiers.
- Sharp edges, contradiction detection: tightens the existing
CONTRADICTS line so the README-level 'catches contradictions'
promise is explicitly qualified — resolution is shipped, automatic
detection is partial (regex-only).
- Sharp edges, sentiment feedback: adds an explicit note that
natural-language sentiment ('ok good', 'no that's wrong') is not
captured automatically; v1.x feedback requires explicit aelf
feedback or MCP aelf:feedback.
- Sharp edges, confidence auto-flag: adds an explicit note that
posterior drops below 0.5 do not surface a warning at v1.x.
…abilities Resolves DROPPED-UNINTENTIONAL items from the agentmemory parity audit that affect the research-line recovery surface: - Adds four 'v2.0.0 candidate' or 'v1.x candidate' rows for orphaned research-line capabilities that were neither shipping nor previously listed: multi-axis uncertainty substrate, speculative/causal edge types, directive-detection triad (REQ-027 enforcement), sentiment- from-prose feedback, near-duplicate audit, multi-model classifier, automatic CONTRADICTS detection. - Adds an explicit 'Deliberately not on this list' section naming five research-line capabilities that aelfrice does not plan to recover: research-artifact provenance metadata + rigor-tier classification (REQ-023/025/026), session-velocity tracking (REQ-024), calibrated status reporting (depends on the two above), cross-project shared scopes (subsumed by federation non-goal), Obsidian vault export + vault-as-source-of-truth storage (rejected; SQLite is the source of truth). The previously-silent narrowing of the research-line surface is now named, so users porting research-line scripts or expectations can see which choices were deliberate vs which are parked-pending-evidence.
Resolves design-principle #5 from the agentmemory parity audit. The research line shipped 17 edge types (12 core + 5 speculative/causal); v1.x ships 6. The narrowing is intentional but was previously silent, which made the omission read as an oversight to anyone porting from the research line. This adds one paragraph naming the missing types and tying their absence to the deferred 'wonder' / multi-axis- uncertainty substrate and the not-yet-shipped onboarding extractors that would produce CALLS/TESTS/IMPLEMENTS/etc. edges.
REQ-010's underlying requirement is filter-bubble prevention (>=15% of retrievals surfacing high-uncertainty beliefs), not Thompson sampling specifically. The previous paragraph named Thompson + UCB as if those were the requirement; they are implementations. Reword: state the actual requirement, acknowledge aelfrice does not yet address it, name determinism as the prioritised property that exploration would break. Keep the v2.x flagged-exploration option open.
…ot observations REQ-013 (research line): observation immutability — no UPDATE/DELETE on the observations table. aelfrice v1 collapses observations into beliefs (which are mutated on decay/feedback), so the strict requirement does not hold as written. The narrowing is real but was previously undocumented. State the substrate explicitly: feedback_history is append-only at v1 and is the immutable substrate for 'did the user actually correct this?' audit. Full ingest-log immutability (per write-log-as-truth.md) is the v2.0 contract. Avoids the appearance that v1 silently dropped immutability; clarifies what v1 *does* keep immutable vs what v2.0 will add.
…oss-link audit issues The single 'wonder / reason / core / unlock / delete / confirm' line at v2.0 was too coarse. Wonder factors into substrate + frontend + lifecycle, with three distinct decision points and three implementation tracks. - Split the wonder line into separate rows: gap-analysis frontend, speculative-belief lifecycle (wonder_ingest + wonder_gc), reason, core/unlock/delete/confirm. - Add v1.5/v1.6 prep row: graph-traversal store methods (expand_graph, get_neighbors, edge_exists). Substrate for wonder + reason; ships ahead of v2.0. - Add v2.0 prep rows for the two side-find gaps: ingest_turn(bulk=) parameter (#194) and scoring.uncertainty_score (#195). - Cross-link the load-bearing substrate decision to its issue (#196). - Cross-link the four v2.x candidate research-line capabilities to their issues: directive-detection triad (#199), sentiment-from-prose (#193), dedup (#197), multimodel (#198), semantic-CONTRADICTS (#201). Reflects findings from the agentmemory parity-audit verify-deeper pass on wonder.py + uncertainty.py.
…s substrate decision The 'Bayesian, not vector' section was silent on whether the (α, β) pair is scalar or per-aspect. The research line shipped a multi-axis UncertaintyVector (4 dimensions: existence/semantics/mechanism/cost) used by speculative beliefs (wonder, reason). aelfrice v1.x is single-axis only. Porting users will assume single-axis from Belief.alpha and Belief.beta_param. Stating the v1 narrowing explicitly avoids confusion when v2.0 either adopts the vector or commits to the scalar form. The substrate decision is load-bearing and tracked at #196.
robotrocketscience
added a commit
that referenced
this pull request
Apr 28, 2026
…gs + telemetry (#232) (#234) Closes #232. Implements the v1.5 retrieval composition plumbing split off from #154 (#154 retargeted as the v1.7 default-on-flip tracker). ## What ships Three atomic commits: 1. **`refactor(retrieval): rename bm25f_enabled -> use_bm25f_anchors per #154 flag policy`** Standardises the v1.5 flag-name surface on `use_<lane>_<modifier>`. Renames kwarg / TOML key / helper across `retrieve()`, `retrieve_with_tiers()`, `retrieve_v2()`, `RetrievalCache.retrieve`. `AELFRICE_BM25F` env var unchanged. #148 just shipped so no released-flag breakage. 2. **`feat(retrieval): placeholder flags + per-lane telemetry`** Four placeholder flags (default-OFF, no-op): `use_signed_laplacian`, `use_heat_kernel`, `use_posterior_ranking`, `use_hrr_structural`. Setting any true in `.aelfrice.toml` emits one stderr warning per process per flag, naming the flag and the tracker issue. Adds `LaneTelemetry` dataclass + `last_lane_telemetry()`; populated in `retrieve()` / `retrieve_with_tiers()` with one assignment each. 3. **`test: composition-tracker placeholder flags + LaneTelemetry`** 8 deterministic tests: warner once-per-process idempotency, empty-TOML quiet, explicit-False quiet, `PLACEHOLDER_FLAGS` regression guard, `LaneTelemetry` populates for FTS5 default + `use_bm25f_anchors=True`, posterior_weight round-trip. ## Acceptance (per #232) - AC1: rename complete across all four surfaces ✅ - AC2: four placeholder flags resolve through env > kwarg > TOML > default ✅ - AC3: stderr warning idempotent per flag per process ✅ - AC4: `LaneTelemetry` populates for both L1 lanes + posterior round-trip ✅ - AC5: byte-identical regression tests preserved (full suite was green at HEAD pre-rebase: 1471 pass / 4 skip; this PR rebases onto current `main` clean and CI staging-gate revalidates). ## Out of scope - No default flips. No new retrieval algorithms. No benchmark gate. Tracked under #154 for the v1.7 wave. ## Note on rebase Branch was 6 commits behind `main` after #211 / #221 / #231 / #202 / #210 / #209 landed. Rebased onto `github/main` with no conflicts. Force-pushed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Eight atomic doc commits resulting from a parity audit against the archived agentmemory research codebase. Splits the coarse v2.0 `wonder` line in ROADMAP into substrate / frontend / lifecycle tracks, cross-links 7 newly-filed parity issues (#193–#201), and lands long-overdue scope clarifications in PHILOSOPHY / LIMITATIONS / ARCHITECTURE.
The audit itself lives in the private aelfrice-lab workspace; this PR contains only the public-facing doc edits derived from it.
Commits (subject + intent)
Companion GitHub issues filed
Test plan