perf(hrr): default dim 2048 -> 512 per lab R4 verdict (#538)

[robotrocketscience]

Summary

Closes #538.

Flips aelfrice.hrr.DEFAULT_DIM from 2048 → 512 to match the lab campaign R4 verdict (closing commit 74cd9d9):

Adopt: HRR full-corpus pass at dim=512 (R1, R4, R5)
Adopt: dim=512 default; dim=2048 escape hatch

Two atomic commits:

1. perf(hrr): flip the constant, update the docstring rationale, fix the ~1/sqrt(dim) and AC8-budget references in hrr_index.py to cite the new default with the dim=2048 escape-hatch number alongside.
2. docs(changelog): Unreleased entry.

Why

• Memory: ~4× reduction. AC8 budget at N=50k goes from ~800 MB to ~200 MB. dim=2048 escape-hatch path remains via the HRRStructIndex(dim=...) kwarg.
• Latency: R4 validated full-corpus pass latency at N=100k holding at p50=20.5ms specifically at dim=512. The public default was shipping at a config the lab didn't latency-budget for at N≥50k.
• Capacity: Plate's bound at dim=512 admits ~57 retrievable bound pairs (dim/9), comfortably above aelfrice's typical ~5 outgoing edges per belief. R3 (capacity stress) holds through K=256 at this dim.

vocab_bridge.py is also a DEFAULT_DIM consumer but is being removed in the #536 cleanup PR — its docstring is left untouched here.

Test plan

• uv run pytest -q → 3090 passed, 53 skipped on the branch tip.
• HRR-specific suites pass at dim=512 (tests/test_hrr.py, tests/test_hrr_struct_index.py, tests/test_retrieve_v2_hrr_structural.py).
• Discretion grep on diff: clean.
• CI matrix (3.12 + 3.13 + analyze + scans + commit-msg-prefix + pr-title/body checks) on PR open.

Summary by Sourcery

Set HRR’s default vector dimensionality to 512 to reduce memory usage and align with lab performance findings.

Enhancements:

• Change the HRR DEFAULT_DIM from 2048 to 512, keeping 2048 as an explicit escape-hatch option for high-multiplicity corpora.
• Update in-code documentation around HRR structural indexing to reflect the new default dimensionality, memory, and noise characteristics.

Documentation:

• Add an unreleased changelog entry documenting the HRR default dimensionality change and its performance and capacity implications.

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

This PR changes the default HRR dimensionality from 2048 to 512 to align with lab campaign R4 performance findings, updates the associated documentation/comments in the HRR implementation to reflect the new default and the 2048 escape-hatch path, and records the change in the Unreleased changelog section.

File-Level Changes

Change	Details	Files
Switch HRR default dimensionality to 512 and document 2048 as an escape-hatch configuration.	Update DEFAULT_DIM constant from 2048 to 512. Revise capacity-related docstring to reference 512-dim capacity (~57 bindings) as the primary rationale and describe 2048 as an option for high-multiplicity corpora. Add references to the lab campaign R4 verdict and its latency findings for the 512-dim default.	src/aelfrice/hrr.py
Align HRR index documentation with the new default dimension and memory profile.	Adjust noise scaling explanation to describe top-K behavior at the default dim=512 instead of dim=2048. Update storage-cost example to show ~200 MB at N=50k for dim=512, and retain ~800 MB as the dim=2048 escape-hatch case. Clarify that both 512 and 2048 configurations remain within the AC8 memory budget while emphasizing 512 as the default.	src/aelfrice/hrr_index.py
Record the HRR default dimensionality flip in the changelog.	Add an Unreleased 'Performance' entry describing the 2048 → 512 default change and its impact on memory footprint and capacity. Document that dim=2048 remains available via the HRRStructIndex(dim=...) kwarg for high-multiplicity corpora. Link the entry to issue [v2.1] hrr.DEFAULT_DIM drift — flip 2048 → 512 to match lab R4 verdict #538 and to the lab campaign verdict that informed the decision.	CHANGELOG.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#538	Change src/aelfrice/hrr.py so that DEFAULT_DIM is 512 instead of 2048, with comments reflecting the lab R4 verdict and escape-hatch role of 2048.	✅
#538	Update usages and documentation that describe the default HRR dimensionality and AC8 memory budget so they reflect dim=512 as the default and dim=2048 as an explicit escape hatch, and ensure no call site silently pins dim=2048.	❌	The PR updates hrr_index.py’s docstrings to describe 512 as the default and 2048 as an escape hatch and does not introduce any code that pins 2048, but it does not modify docs/feature-hrr-vocab-bridge.md, which the issue explicitly calls out for updating the AC8 memory line to the dim=512 default.
#538	Add a CHANGELOG entry under the next release documenting the hrr.DEFAULT_DIM change.	✅

Possibly linked issues

• [v2.1] hrr.DEFAULT_DIM drift — flip 2048 → 512 to match lab R4 verdict #538: The PR performs the DEFAULT_DIM 2048→512 flip, updates hrr_index docs, and adds the requested changelog entry.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Warning

Rate limit exceeded

@robotrocketscience has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 21 minutes and 5 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 46bd2307-b933-4955-aa1b-dbed73524c40

📥 Commits

Reviewing files that changed from the base of the PR and between 37e0764 and 974f764.

⛔ Files ignored due to path filters (1)

• CHANGELOG.md is excluded by !**/CHANGELOG.md

📒 Files selected for processing (2)

• src/aelfrice/hrr.py
• src/aelfrice/hrr_index.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-538-default-dim

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[robotrocketscience]

[claim:review:Curie:2026-05-10T04:19:36Z]

[robotrocketscience]

[claim:review:Planck:2026-05-10T04:21:21Z]

[robotrocketscience]

[release:review:Planck:2026-05-10T04:21:25Z]

[robotrocketscience]

[release:review:Curie:2026-05-10T04:21:57Z]