docs(readme): plain rewrite — drop emoji/HTML-slop, fix inconsistencies#44
Conversation
…nsistencies
Rewrites README.md in the understated, prose-first style of the reference
repos (gajae-code / firecrawl): one centered hero block, everything else
plain markdown.
- No emoji anywhere (was ~48 emoji headings + checklist bullets).
- Raw HTML confined to the hero block + one <details> (was four <table>
blocks with embedded code).
- 894 -> ~338 lines: the same 6-7 surfaces were explained in four
overlapping tables; collapsed to one canonical Surfaces table. The three
"Companion" sections and two quick-starts are merged.
- Strips all internal dev jargon (PR #, THR-/REV-/T3.x, "closes #").
- Fixes factual inconsistencies surfaced by review:
- corpus count unified to 80 sessions / 28 projects / 79 indexed /
17,752 tool calls (was 258 vs 79/80; 17,938 vs 17,752 — the latter
logically impossible).
- collection name memex_sessions_v3 (was stale memex_sessions).
- landing links -> https://memex.quest (was the old github.io URL).
- Tones down the data-loss section to a neutral ownership framing (no
vendor named pejoratively); leads with the Qdrant value, not a grievance.
- Adds a brief personal -> team -> Enterprise (Qdrant Cloud) roadmap note.
Verified: 12 MCP tools, all CLI commands, vectors/schema, and test counts
checked against the code; zero emoji and anchors resolve.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 11 minutes and 21 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
WalkthroughREADME.md 전체가 Qdrant 기반 제품 정의, MCP 에이전트 통합, 아키텍처 상세화, 현재 상태 및 로드맵으로 일관되게 갱신되었습니다. 프로젝트 소개부터 빠른 시작, 아키텍처 다이어그램, 기술 스택, 상태 및 기여 안내가 최신 내용으로 재작성되고 정리되었습니다. ChangesREADME.md 문서 전체 갱신
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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 |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors and significantly condenses the README.md file, simplifying the project description, feature lists, and installation instructions for a cleaner presentation. Additionally, a syntax error was identified in the Mermaid architecture diagram where a bidirectional link with text was incorrectly formatted, which would cause rendering issues.
| webview["Webview (HTML/CSS/JS)<br>Time Machine · topology · replay · banner"] | ||
| rustcore["Rust core<br>parser · indexer · companion · wrapped<br>loopcheck · redact · hook · install"] | ||
| webview <-- "Tauri IPC<br>invoke('lens_search', …)" --> rustcore | ||
| webview <-- "Tauri IPC" --> rustcore |
There was a problem hiding this comment.
In Mermaid, using <-- "text" --> is syntactically invalid and will cause a rendering error (showing a "Syntax error in graph" box instead of the flowchart). To define a bidirectional link with text, use the standard -- "text" <--> or <-->|text| syntax.
| webview <-- "Tauri IPC" --> rustcore | |
| webview -- "Tauri IPC" <--> rustcore |
…stall - Lead Download with 'brew install --cask two-weeks-team/tap/memex'. - Bump version 0.1.0 -> 0.1.2; the v0.1.2 DMG (~19 MB) is Developer-ID signed and notarized, so drop the unsigned/Gatekeeper/xattr workaround. - Remove the now-shipped 'code signing / notarization' deferred row. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8589d46f68
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| — `Memex_0.1.2_aarch64.dmg` (~19 MB), signed with a Developer ID and notarized, | ||
| so it opens without a Gatekeeper warning. Drag **Memex.app** to `/Applications`. |
There was a problem hiding this comment.
This now tells macOS users the v0.1.2 DMG is Developer ID signed/notarized and will open without Gatekeeper, but the same tree's install/evidence docs still describe the shipped app as ad-hoc signed, not notarized, and requiring the Gatekeeper bypass steps. In the clean-install path where README is the entry point, users will skip the required quarantine/right-click instructions and think the download is broken; either update the artifact plus docs together or keep this README section on the unsigned flow.
Useful? React with 👍 / 👎.
…hreads) The team contributed with_intra_threads (configurable ONNX intra-op thread count) to fastembed-rs (Anush008/fastembed-rs#255), merged and shipped in 5.15. Memex consumes it via MEMEX_EMBED_THREADS to cap embedding CPU so the desktop UI stays responsive. Note the version (fastembed-rs 5.15) and add a short upstream-contribution line to Status. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 242ef3a860
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| # collection per iteration. | ||
| memex install all [--hooks] [--dry-run] # wire MCP + hooks into Claude / Codex / Cursor | ||
| memex install uninstall # remove every memex-tagged block | ||
| memex serve --port 8765 --ui-dir src # headless UI + JSON API + HTTP MCP (web variant) |
There was a problem hiding this comment.
In the default Quick start/release path users build the GUI binary (cargo build --release here, and the release workflow uses --features gui), but the serve subcommand is compiled only under #[cfg(feature = "web")] in src-tauri/src/cli.rs. Listing memex serve --port 8765 --ui-dir src as an ordinary CLI command means users following this README will get an unrecognized subcommand unless they know to build with the web feature; please either mark this line as web-feature-only with the required build command or move it out of the default CLI list.
Useful? React with 👍 / 👎.
Mirror the landing's Run section: the README only linked to the server variant, so add the three Docker commands (build -> run -> claude mcp add --transport http) inline. Gives non-macOS judges a runnable path and matches the landing. Also note the watcher reads ~/.codex/sessions, not just ~/.claude/projects. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mirror the landing footer's curated doc set in the README: replace the scattered 'Deeper reading' list with one Documentation section grouped Architecture / Agent integration / Evidence / Install & build, so all the key docs are exposed in one place (and the README and landing stay in sync). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…prose) Add a brief, plain two-sentence nod to Bush's 1945 memex in 'Why Memex' — associative trails, not search boxes — which is also the project's anti-chatbot thesis and keeps the README in tone with the landing. Drops the original's dense italic hero epigraph in favor of calm prose. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…start Surface the LLM/agent angle at quick-start time: memex install all (MCP + hooks) and memex memory --cwd (a paste-able memory primer for an LLM), with a cross-link to the MCP tools section. memex's whole point is agent memory, so it belongs in the first-run flow, not only the MCP section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4218e83d4f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| npm run tauri build # local release build (WebKit Inspector ON) | ||
| # OR — distribution build (.dmg you'd hand to someone else) | ||
| npm run tauri:dist # → bundle/dmg/Memex_*.dmg, Inspector OFF for shipping | ||
| memex install all # register the MCP server + hooks for Claude Code / Codex / Cursor |
There was a problem hiding this comment.
Here the quick start says memex install all wires hooks, but the installer leaves Claude hooks disabled unless --hooks is passed: InstallOptions::default() sets hooks: false, and install_claude only merges the hook block inside if opts.hooks. Users following this step to get SessionStart/UserPromptSubmit/PostToolUse/SessionEnd memory injection will only register the MCP/Codex/Cursor/shell pieces and silently miss the proactive hooks; either use memex install all --hooks here or remove “hooks” from the comment.
Useful? React with 👍 / 👎.
Mirror the oh-my-opencode install pattern in the README Quick start: a 'For humans' paste-prompt and a 'For coding agents' curl, both pointing at docs/INSTALL.md. Rewrite docs/INSTALL.md so that target is accurate and agent-followable: - was fully stale (unsigned / v0.1.0 / Gatekeeper dance, no Homebrew); - now: Homebrew (signed+notarized) / DMG v0.1.2 / source build, shared setup (Qdrant, Full Disk Access, index into memex_sessions_v3, optional MCP wiring), and a verify step. Numbered + explicit so an agent can execute it top to bottom. - fixes the stale ../README.md#-quick-start anchor. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: bd5972698b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **Fix 2 — clear the quarantine flag (Terminal):** | ||
| ```bash | ||
| xattr -dr com.apple.quarantine /Applications/Memex.app | ||
| bash scripts/start-qdrant.sh # starts qdrant/qdrant:v1.18.1 on :6334 (gRPC) / :6333 (REST) |
There was a problem hiding this comment.
For users following the recommended Homebrew or DMG paths above, this shared setup block is the next step but they have not cloned the repo, so bash scripts/start-qdrant.sh fails before Qdrant is started. The Docker fallback is only mentioned after the failing command; put the Docker command in the main shared path for Homebrew/DMG users or scope this script command to the source-build path.
Useful? React with 👍 / 👎.
The MEMEX_EMBED_THREADS cap is opt-in (default = all cores, unchanged); the prior wording implied the UI stays responsive automatically. Reword to 'opt-in ... can be capped' so it matches the code (embed_intra_threads() only acts when the env var is set). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3aa5b20888
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| (If you installed the app via Homebrew/DMG and don't have the repo, run Qdrant | ||
| with Docker: `docker run -d -p 6333:6333 -p 6334:6334 qdrant/qdrant:v1.18.1`.) |
There was a problem hiding this comment.
For Homebrew/DMG users this fallback starts Qdrant with Docker's default host bind on all interfaces, while the repo's normal docker-compose.yml deliberately uses 127.0.0.1:6333/6334 because the unauthenticated Qdrant API/dashboard contains the local session index. On a shared network, following this command exposes the Memex collection off-machine; make the fallback publish only to loopback, e.g. 127.0.0.1:6333:6333 and 127.0.0.1:6334:6334.
Useful? React with 👍 / 👎.
| ```bash | ||
| memex scan --index # downloads the BGE-small model (~130 MB) on first run |
There was a problem hiding this comment.
When users choose path A or B, the guide only installs Memex.app; the only PATH setup is in the source-build section above, so DMG users who reach this shared step will get memex: command not found before they can index or install agent integration. Add a PATH/symlink step for /Applications/Memex.app/Contents/MacOS/memex (or give the equivalent full command/app flow) before using the bare memex command in the shared setup.
Useful? React with 👍 / 👎.
1 participant
Rewrites
README.mdin the understated, prose-first style of the reference repos (one centered hero block, everything else plain markdown).Preview the exact GitHub rendering: https://github.com/Two-Weeks-Team/memex/blob/docs/readme-clean-rewrite/README.md
Changes
<details>(was four<table>blocks with embedded code).PR #,THR-/REV-/T3.x,closes #).memex_sessions_v3(was stalememex_sessions).github.ioURL).Verification
Two independent review passes (accuracy vs code; style/no-loss) both returned ship: 12 MCP tools + names, all CLI commands, vectors/schema, collection name, and
290+test count checked against the code; zero pictographic emoji; all five hero anchors resolve; alldocs/img/*screenshots exist. Content-only change — does not touchindex.html/assets, so it does not trigger the landing deploy.🤖 Generated with Claude Code
Summary by CodeRabbit