docs: Phase 9b — README rewrite, CONTRIBUTING update#19
Conversation
README.md: rewrite with mermaid architecture diagram, all 14 MCP tools documented, enrichment details (10 fields, MLX/Ollama backends), full config reference (12 env vars), data sources table, comparison matrix (updated for 14 tools + session analysis), quick-start with multi-editor MCP setup, testing section. CONTRIBUTING.md: updated project structure (matches actual codebase), key patterns (error handling, logging, env vars), how to add an MCP tool, correct test counts (268). pyproject.toml: updated description, added Python 3.13 classifier and AI topic. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the 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. 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughDocumentation and configuration updates across three files: CONTRIBUTING.md is restructured with enhanced development setup, MCP tool development guidance, and code patterns; README.md updates badges (Python 3.11+, 14 MCP tools, 268 tests), tool descriptions, and architecture sections; pyproject.toml adds Python 3.13 support and AI topic classifier. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
pyproject.toml (1)
27-27:⚠️ Potential issue | 🟠 Major
mcp>=1.0.0is severely under-constrained — tighten to>=1.26.0,<2Two problems exposed by this PR's own documentation:
Lower bound is ~26 minor versions behind what the README advertises. The architecture table added in this PR documents "MCP SDK v1.26+", yet the constraint permits any version back to 1.0.0 (released Nov 2024), which predates the tool annotation, structured-output, and elicitation APIs relied on by the 14 MCP tools.
No upper bound against the upcoming v2 breaking release.
mcp>=1.25,<2is the vendor-recommended pin for code that must stay on v1.x, with an anticipated stable v2 release in Q1 2026. Without an upper bound, users whopip install brainlayerafter v2 ships will get an incompatible SDK.🔧 Proposed fix
- "mcp>=1.0.0", + "mcp>=1.26.0,<2",🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@pyproject.toml` at line 27, The pyproject dependency constraint "mcp>=1.0.0" is too loose; update the requirement in pyproject.toml to pin to the supported MCP v1 line by replacing "mcp>=1.0.0" with a tightened range "mcp>=1.26.0,<2" so the package requires at least the v1.26 SDK features and prevents accidental upgrades to a breaking v2 release.README.md (1)
34-56:⚠️ Potential issue | 🟡 MinorMD031: fenced code blocks inside
<details>need surrounding blank linesThree blocks inside the collapsible section (lines 34, 48, 70) trigger MD031 because they open immediately after a heading or paragraph without a preceding blank line. This can cause rendering inconsistencies in some Markdown parsers.
🔧 Proposed fix (representative — apply same pattern to lines 48 and 70)
**Claude Code** (`~/.claude.json`): + ```json { "mcpServers": {**Cursor** (MCP settings): + ```json {**VS Code** (`.vscode/mcp.json`): + ```json {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 34 - 56, The MD031 errors are caused by fenced code blocks opening immediately after text inside the collapsible section; fix by inserting a single blank line immediately before each fenced code block that contains the JSON snippet (the blocks starting with ```json and containing "mcpServers": { ... } and "brainlayer": { "command": "brainlayer-mcp" }), i.e., add a blank line before each triple-backtick fence in the <details> collapsible so each code block is separated from the preceding paragraph or heading.
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (3)
CONTRIBUTING.mdREADME.mdpyproject.toml
🧰 Additional context used
📓 Path-based instructions (1)
**/{setup.py,pyproject.toml,requirements*.txt,Pipfile,*.lock}
📄 CodeRabbit inference engine (CLAUDE.md)
Install and use uv for Python dependency management instead of pip
Files:
pyproject.toml
🧠 Learnings (2)
📚 Learning: 2026-02-20T18:33:59.833Z
Learnt from: CR
Repo: EtanHey/brainlayer PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T18:33:59.833Z
Learning: Applies to **/mcp/__init__.py : Implement MCP server with 14 tools for Claude integration (search, stats, context, file_timeline, operations, regression, plan_links, session_summary, etc.)
Applied to files:
README.md
📚 Learning: 2026-02-20T18:33:59.833Z
Learnt from: CR
Repo: EtanHey/brainlayer PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-02-20T18:33:59.833Z
Learning: Maintain separation between read-only source conversations in ~/.claude/projects/ and mutable indexed database in ~/.local/share/brainlayer/
Applied to files:
README.md
🪛 LanguageTool
README.md
[uncategorized] ~231-~231: The official name of this popular video platform is spelled with a capital “T”.
Context: ... | | YouTube | Transcripts via yt-dlp | brainlayer index --source youtube | | Markdown | Any .md files | `brai...
(YOUTUBE)
🪛 markdownlint-cli2 (0.21.0)
CONTRIBUTING.md
[warning] 16-16: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
README.md
[warning] 16-16: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 34-34: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 48-48: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 70-70: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Cursor Bugbot
- GitHub Check: test (3.11)
- GitHub Check: test (3.13)
- GitHub Check: test (3.12)
🔇 Additional comments (1)
README.md (1)
202-203: Default model size and hardware requirements should be documented in quick-startThe default quantization (
glm-4.7-flash:latest) is 19 GB. This is a substantial implicit hardware requirement that is not surfaced anywhere in the README's quick-start or enrichment section.Consider documenting these constraints explicitly, or defaulting to a smaller/widely-available model and recommending
glm-4.7-flashas an upgrade.Likely an incorrect or invalid review comment.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CONTRIBUTING.md`:
- Line 91: The test uses a hardcoded tool count in
test_think_recall_integration.py which breaks whenever tools change; update the
test to compute the expected count dynamically by calling the runtime tool
registry (e.g., use len(server.list_tools()) or equivalent API available in that
test) and assert against that value instead of a magic number; ensure the test
imports/accepts the same server/fixture used elsewhere in the suite and replace
the hardcoded literal with the dynamic len(...) call so the assertion stays
correct as tools are added/removed.
- Around line 16-37: Add a language specifier to the fenced directory-tree code
block in CONTRIBUTING.md (the triple-backtick block that lists src/brainlayer/
and its subfolders) by changing the opening fence to include "text" (e.g.,
```text) so the markdown linter MD040 is satisfied and the block is treated as
non-executable plain text.
In `@pyproject.toml`:
- Around line 48-50: Update the minimum dependency versions in pyproject.toml to
ones that ship cp313 wheels: set apsw to >=3.46.1, bump spacy to >=3.8, and
choose a sentence-transformers release that explicitly declares Python
3.13/wheels (or require a compatible PyTorch >=2.6.0 if you prefer not to pin);
modify the dependency entries in pyproject.toml accordingly so CI and users
install native cp313 wheels instead of building from source.
In `@README.md`:
- Line 8: Update the tests badge text in the README to accurately reflect the PR
description: modify the alt/label portion of the badge markup
"[](`#testing`)"
so it either reads "266 passing" (to match 266 passing + 2 skipped) or "268
tests" (to indicate total tests); adjust the URL segment and escaped space %20
accordingly so the rendered badge matches the chosen text.
---
Outside diff comments:
In `@pyproject.toml`:
- Line 27: The pyproject dependency constraint "mcp>=1.0.0" is too loose; update
the requirement in pyproject.toml to pin to the supported MCP v1 line by
replacing "mcp>=1.0.0" with a tightened range "mcp>=1.26.0,<2" so the package
requires at least the v1.26 SDK features and prevents accidental upgrades to a
breaking v2 release.
In `@README.md`:
- Around line 34-56: The MD031 errors are caused by fenced code blocks opening
immediately after text inside the collapsible section; fix by inserting a single
blank line immediately before each fenced code block that contains the JSON
snippet (the blocks starting with ```json and containing "mcpServers": { ... }
and "brainlayer": { "command": "brainlayer-mcp" }), i.e., add a blank line
before each triple-backtick fence in the <details> collapsible so each code
block is separated from the preceding paragraph or heading.
| 2. Add the handler function (prefix with `_`) | ||
| 3. Add the routing in `call_tool` | ||
| 4. Add `ToolAnnotations` (readOnlyHint, etc.) | ||
| 5. Update the tool count in `test_think_recall_integration.py` |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Hardcoded tool count in integration test is a maintenance hazard
Every time a tool is added or removed, contributors must remember to update the assertion in test_think_recall_integration.py and re-read the checklist item. A test that introspects the tool list dynamically (e.g., len(server.list_tools())) would be more robust.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CONTRIBUTING.md` at line 91, The test uses a hardcoded tool count in
test_think_recall_integration.py which breaks whenever tools change; update the
test to compute the expected count dynamically by calling the runtime tool
registry (e.g., use len(server.list_tools()) or equivalent API available in that
test) and assert against that value instead of a magic number; ensure the test
imports/accepts the same server/fixture used elsewhere in the suite and replace
the hardcoded literal with the dynamic len(...) call so the assertion stays
correct as tools are added/removed.
| "Programming Language :: Python :: 3.13", | ||
| "Topic :: Software Development :: Libraries", | ||
| "Topic :: Scientific/Engineering :: Artificial Intelligence", |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat pyproject.tomlRepository: EtanHey/brainlayer
Length of output: 3232
🏁 Script executed:
python3 - <<'EOF'
import json, urllib.request
packages = {
"apsw": "3.45.0",
"sqlite-vec": "0.1.3",
"sentence-transformers": "2.2.0",
"tree-sitter": "0.21.0",
"spacy": "3.7.0",
"numpy": "1.22.0",
"scikit-learn": "1.0.0",
}
for pkg, min_ver in packages.items():
url = f"https://pypi.org/pypi/{pkg}/{min_ver}/json"
try:
with urllib.request.urlopen(url, timeout=10) as r:
data = json.loads(r.read())
classifiers = data["info"].get("classifiers", [])
py313 = any("3.13" in c for c in classifiers)
wheels = [f["filename"] for f in data.get("urls", []) if "cp313" in f.get("filename","")]
print(f"{pkg}=={min_ver}: py3.13 classifier={py313}, cp313 wheels={bool(wheels)}")
except Exception as e:
print(f"{pkg}=={min_ver}: ERROR {e}")
EOFRepository: EtanHey/brainlayer
Length of output: 1133
🏁 Script executed:
find . -type f \( -name ".github" -o -name "*.yml" -o -name "*.yaml" \) | grep -E "(github|gitlab|travis|circleci)" | head -20Repository: EtanHey/brainlayer
Length of output: 120
🏁 Script executed:
find .github/workflows -type f -name "*.yml" -o -name "*.yaml" 2>/dev/null | xargs cat 2>/dev/null | head -100Repository: EtanHey/brainlayer
Length of output: 1821
🌐 Web query:
apsw 3.45.0 Python 3.13 support wheels
💡 Result:
APSW 3.45.0.0 (released Jan 16, 2024) does not ship Python 3.13 (cp313) wheels—its published wheels are only for cp38–cp312 (plus sdist). [1]
If you need Python 3.13 wheels, you must use a newer APSW release (for example 3.46.1.0 includes cp313 wheels such as cp313-win_amd64, cp313-win32, and cp313-musllinux_*). [2]
Sources: [1] [2]
🌐 Web query:
sentence-transformers 2.2.0 Python 3.13 compatibility
💡 Result:
sentence-transformers==2.2.0 (released Feb 10, 2022) predates Python 3.13 and does not declare any Requires-Python constraint on PyPI (it’s empty), so pip may try to install it on 3.13—but that doesn’t mean the dependency stack will work. [1], [2]
In practice, Python 3.13 compatibility is gated by PyTorch (a required dependency). PyTorch added Python 3.13 support in the PyTorch 2.6.0 release notes. [3] Historically, attempts to use sentence-transformers on Python 3.13 failed specifically because PyTorch didn’t support 3.13 yet (before those newer PyTorch releases). [4]
So the safe conclusions are:
- No official/explicit Python 3.13 support signal exists for
sentence-transformers==2.2.0(it’s from 2022 and only lists old Python classifiers). [1] - Even if it installs, it will only work if you also install a PyTorch build that supports Python 3.13 (i.e., modern PyTorch). [3]
- Mixing a 2022
sentence-transformerswith modern PyTorch/Transformers may cause runtime/API incompatibilities; the recommended fix is typically upgrade sentence-transformers (instead of pinning to 2.2.0) or use Python 3.12. [4]
Sources:
[1] PyPI – sentence-transformers 2.2.0 project page (release date, recommended deps/classifiers) (pypi.org)
[2] PyPI JSON metadata – sentence-transformers 2.2.0 (requires_python empty) (pypi.org)
[3] PyTorch GitHub releases – PyTorch 2.6.0 notes (Python 3.13 support mentioned) (github.com)
[4] GitHub discussion (asreview) – notes that PyTorch dependency lacked Python 3.13 support (and suggests Python 3.12 / nightly PyTorch) (github.com)
Citations:
- 1: https://pypi.org/project/sentence-transformers/2.2.0/
- 2: https://pypi.org/pypi/sentence-transformers/2.2.0/json
- 3: https://github.com/pytorch/pytorch/releases?utm_source=openai
- 4: Cannot install sentence-transformers to use sentence BERT asreview/asreview#1945
🌐 Web query:
spacy 3.7 Python 3.13 wheels
💡 Result:
spaCy 3.7.x does not ship Python 3.13 (cp313) wheels. On PyPI for spacy==3.7.2, the published wheels are for CPython 3.11 and 3.12 (plus the sdist), but no cp313 wheels are listed. [1]
If you need Python 3.13 wheels, you’ll need a newer spaCy release: the current PyPI project page shows cp313 wheels available (e.g., manylinux, macOS arm64, Windows arm64). [2]
What to do:
- Stay on spaCy 3.7 → use Python 3.12 (or 3.11). [1]
- Stay on Python 3.13 → upgrade spaCy to a version that provides cp313 wheels (e.g., 3.8.x). [2]
Sources:
[1] PyPI: spacy 3.7.2 files / supported Python versions (no cp313 wheels) (pypi.org)
[2] PyPI: spacy latest (shows cp313 wheels available) (pypi.org)
Citations:
CI is testing Python 3.13, but minimum dependency versions lack wheels—consider bumping to versions with cp313 builds
Python 3.13 CI coverage is confirmed (test matrix includes 3.13), so the critical question is addressed. However, your minimum versions still lack cp313 wheels:
- apsw==3.45.0: No cp313 wheels (only cp38–cp312); cp313 wheels available in 3.46.1+
- spacy==3.7.x: No cp313 wheels (only cp311–cp312); cp313 wheels available in 3.8+
- sentence-transformers==2.2.0: No explicit Python 3.13 support (2022 release); only works if PyTorch ≥2.6.0 is installed
These packages install via source distributions on 3.13 (which explains CI passes), but true "first-class support" typically means shipping wheels. For optimal user experience and faster installs, consider bumping to versions with native cp313 wheels.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@pyproject.toml` around lines 48 - 50, Update the minimum dependency versions
in pyproject.toml to ones that ship cp313 wheels: set apsw to >=3.46.1, bump
spacy to >=3.8, and choose a sentence-transformers release that explicitly
declares Python 3.13/wheels (or require a compatible PyTorch >=2.6.0 if you
prefer not to pin); modify the dependency entries in pyproject.toml accordingly
so CI and users install native cp313 wheels instead of building from source.
- Fix tests badge: 268 → 266 (2 are skipped, not passing) - Add language specifier to CONTRIBUTING.md directory tree block (MD040) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 participant
Summary
Phase 9b of the Layers v2 Launch plan — README + docs polish for public release.
README.md (full rewrite)
BRAINLAYER_*env vars with defaults[style])CONTRIBUTING.md (updated)
pyproject.toml
Test plan
🤖 Generated with Claude Code
Note
Low Risk
Documentation and metadata-only changes; no runtime logic or security-sensitive code paths are modified.
Overview
Updates public docs for release readiness by rewriting
README.mdwith clearer positioning, updated badges/test counts, multi-editor MCP setup, an architecture diagram, and expanded sections covering tool catalog (14 MCP tools), enrichment, configuration env vars, supported data sources, and testing commands.Refreshes
CONTRIBUTING.mdwith a modern dev setup (venv +.[dev]), accurate project structure, explicit test/lint workflows, PR process expectations, and checklists/patterns for adding MCP tools.Updates
pyproject.tomlmetadata by revising the project description and adding new trove classifiers (Python 3.13, AI topic).Written by Cursor Bugbot for commit 9adeae6. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
Release Notes
Documentation
Chores