docs: fix drift in Docker & Local Dev - #258
Conversation
Routine docs-accuracy audit against verygoodplugins/automem@main. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FX7QQ4GSzzAbonMyeNDYzJ
![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: 0bb9c07179
ℹ️ 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".
| ``` | ||
|
|
||
| The server binds to `[::]` (IPv6 dual-stack) on port 8001. | ||
| `app.py` logs a single line before initializing FalkorDB, Qdrant, and the enrichment/embedding/consolidation workers — there is no per-step "connecting to..." or "worker started" logging. If initialization fails partway through, the process logs the failed step and exits (`sys.exit(1)`) rather than continuing to serve traffic. The server binds to `[::]` (IPv6 dual-stack) on port 8001. |
There was a problem hiding this comment.
When Qdrant is absent or unreachable during bare-metal startup, AutoMem continues in graph-only mode with Qdrant disconnected, as this page itself states below and the API reference documents; it does not exit. The unconditional claim that any partial initialization failure calls sys.exit(1) therefore gives developers the wrong diagnosis for this supported configuration. Limit it to fatal initialization failures.
Useful? React with 👍 / 👎.
| | `qdrant` | string | Qdrant connection: `"connected"` or `"disconnected"` | | ||
| | `memory_count` | integer | Total memories in the graph | | ||
| | `vector_count` | integer | Total points in the Qdrant collection | | ||
| | `sync_status` | string | `"synced"`, `"drift_detected"` (fewer vectors than memories), or `"orphaned_vectors"` (more vectors than memories) | |
There was a problem hiding this comment.
unknown sync status
When either database count cannot be collected, such as when Qdrant is disconnected, /health can return sync_status: "unknown"; the API and operations health references list that value. Omitting it here leaves readers unable to interpret a valid response precisely in the failure mode newly described immediately below.
Useful? React with 👍 / 👎.
| | `falkordb` | string | FalkorDB connection: `"connected"` or `"disconnected"` | | ||
| | `qdrant` | string | Qdrant connection: `"connected"` or `"disconnected"` | | ||
| | `memory_count` | integer | Total memories in the graph | | ||
| | `vector_count` | integer | Total points in the Qdrant collection | |
There was a problem hiding this comment.
vector_count as nullable
When Qdrant is unavailable—the supported degraded mode described below—/health returns vector_count: null, not an integer; both the API and operations health references document this. Advertising an unconditional integer can make health-check consumers reject the very degraded response this page instructs users to handle.
Useful? React with 👍 / 👎.
Deploying automem-website with
|
| Latest commit: |
ba2d0e3
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://af539a80.automem-website.pages.dev |
| Branch Preview URL: | https://docs-audit-getting-started-d.automem-website.pages.dev |
Scope the sys.exit(1) claim to genuinely fatal init failures (FalkorDB/Qdrant connection errors are caught internally and degrade gracefully per automem/stores/runtime_clients.py — only a VectorDimensionMismatchError is re-raised as fatal), and document the nullable vector_count / "unknown" sync_status values that automem/api/health.py returns when a count can't be collected. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FX7QQ4GSzzAbonMyeNDYzJ
|
Addressed all three Codex P2 comments in ba2d0e3, verified against
Generated by Claude Code |
2 participants
Routine docs-accuracy audit of
src/content/docs/docs/getting-started/docker.mdagainstverygoodplugins/automem@main(never previously reviewed — page is a Getting Started twin ofdeployment/docker.md, which has been audited separately).FLASK_DEBUG=1)app.pystarts viarun_default_server(), which hardcodesapp.run(host="::", port=port, debug=False).FLASK_ENV/FLASK_DEBUGare set indocker-compose.ymlbut never read anywhere in the codebase (confirmed via repo-wide search) — Werkzeug's reloader is never active.docker compose restart flask-apiormake stop && make dev) after edits. Updated the two other mentions of "hot-reload" in the volume table and env-var notes for consistency.--dir /dataas part ofREDIS_ARGSdocker-compose.yml's own comment says--diris not set inREDIS_ARGSbecause FalkorDB's entrypoint always appends--dir $FALKORDB_DATA_PATHafter it, silently overriding anything inREDIS_ARGS. The doc's own copy already includesFALKORDB_DATA_PATH=/dataas a separate line further down, so this was an internal inconsistency.--dirbullet from theREDIS_ARGSlist; added a sentence explainingFALKORDB_DATA_PATHis the actual mechanism.[INFO] Loading configuration...,Connecting to FalkorDB...,FalkorDB connected successfully,Starting enrichment worker thread, etc.automemrepo (verified via code search). The only log line actually emitted at startup islogger.info("Starting Flask API on port %s", port), in the real%(asctime)s | %(levelname)s | %(name)s | %(message)sformat.sys.exit(1))./healthexample response and field table (falkordb/qdrant:"connected"/"unavailable"/"not configured"; fields limited tostatus,falkordb,qdrant,memory_count,enrichment.status,enrichment.queue_depth,graph)automem/api/health.pyonly ever returns"connected"/"disconnected"forfalkordb/qdrant(never"unavailable"/"not configured"), and the response also includesvector_count,sync_status,vector_dimensions(configured/effective/collection/mismatch),enrichment.pending/inflight/processed/failed, andtimestamp— none of which were documented. Also,statusbecomes"degraded"(not"healthy") whenever either database is disconnected, which the old note undersold."connected"is the expected steady state;"disconnected"+status: "degraded"is what actually appears if Qdrant isn't configured).No other issues found on this page — volumes, port mappings,
depends_onhealth-check semantics, and the Makefile command table all matched current source.Verified against: verygoodplugins/automem@4b5eaaf (
docker-compose.yml,Makefile,Dockerfile,app.py,automem/runtime_wiring.py,automem/runtime_environment.py,automem/api/health.py,automem/config.py)Generated by Claude Code as part of the recurring automem-docs-review routine.
Generated by Claude Code