From 638bda6b62cf79b51f802b6fccbedb4789aa3df8 Mon Sep 17 00:00:00 2001 From: "Charles P. Cross" <8572939+cpdata@users.noreply.github.com> Date: Mon, 20 Oct 2025 04:41:08 -0400 Subject: [PATCH] Adopt Beads issue tracking --- .beads/.gitignore | 2 + .beads/issues.jsonl | 94 ++ AGENTS.md | 104 +- CHANGELOG.md | 9 + ISSUES.md | 5 +- TODO.md | 104 +- reference-docs/Beads-AGENTS.md | 449 ++++++++ reference-docs/Beads-CHANGELOG.md | 452 ++++++++ reference-docs/Beads-CLAUDE.md | 5 + reference-docs/Beads-CONTRIBUTING.md | 262 +++++ reference-docs/Beads-EXTENDING.md | 570 +++++++++ reference-docs/Beads-LABELS.md | 531 +++++++++ reference-docs/Beads-LINTING.md | 123 ++ reference-docs/Beads-PLUGIN.md | 329 ++++++ reference-docs/Beads-QUICKSTART.md | 104 ++ reference-docs/Beads-README.md | 1593 ++++++++++++++++++++++++++ reference-docs/Beads-RELEASING.md | 150 +++ reference-docs/Beads-SECURITY.md | 88 ++ reference-docs/Beads-TEXT_FORMATS.md | 523 +++++++++ reference-docs/Beads-WORKFLOW.md | 620 ++++++++++ 20 files changed, 6005 insertions(+), 112 deletions(-) create mode 100644 .beads/.gitignore create mode 100644 .beads/issues.jsonl create mode 100644 reference-docs/Beads-AGENTS.md create mode 100644 reference-docs/Beads-CHANGELOG.md create mode 100644 reference-docs/Beads-CLAUDE.md create mode 100644 reference-docs/Beads-CONTRIBUTING.md create mode 100644 reference-docs/Beads-EXTENDING.md create mode 100644 reference-docs/Beads-LABELS.md create mode 100644 reference-docs/Beads-LINTING.md create mode 100644 reference-docs/Beads-PLUGIN.md create mode 100644 reference-docs/Beads-QUICKSTART.md create mode 100644 reference-docs/Beads-README.md create mode 100644 reference-docs/Beads-RELEASING.md create mode 100644 reference-docs/Beads-SECURITY.md create mode 100644 reference-docs/Beads-TEXT_FORMATS.md create mode 100644 reference-docs/Beads-WORKFLOW.md diff --git a/.beads/.gitignore b/.beads/.gitignore new file mode 100644 index 0000000..6d861e0 --- /dev/null +++ b/.beads/.gitignore @@ -0,0 +1,2 @@ +*.db +*.db-* diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl new file mode 100644 index 0000000..71b3649 --- /dev/null +++ b/.beads/issues.jsonl @@ -0,0 +1,94 @@ +{"id":"meshmind-1","title":"Implement dependency guards and lazy imports for optional packages (`pymgclient`, `tiktoken`, `celery`, `sentence-transformers`).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:52.797024183Z","updated_at":"2025-10-20T08:10:52.86662767Z","closed_at":"2025-10-20T08:10:52.86662767Z"} +{"id":"meshmind-10","title":"Expand Makefile and add CI workflows for linting, testing, and type checks.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.918296644Z","updated_at":"2025-10-20T08:10:53.973078365Z","closed_at":"2025-10-20T08:10:53.973078365Z"} +{"id":"meshmind-11","title":"Document or provision local Memgraph and Redis services (e.g., via docker-compose) for onboarding.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.025267286Z","updated_at":"2025-10-20T08:10:54.081014834Z","closed_at":"2025-10-20T08:10:54.081014834Z"} +{"id":"meshmind-12","title":"Abstract `GraphDriver` to support alternative storage backends (Neo4j, in-memory, SQLite prototype).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.134743488Z","updated_at":"2025-10-20T08:10:54.212885499Z","closed_at":"2025-10-20T08:10:54.212885499Z"} +{"id":"meshmind-13","title":"Add service interfaces (REST/gRPC) for ingestion and retrieval.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.27073895Z","updated_at":"2025-10-20T08:10:54.3240942Z","closed_at":"2025-10-20T08:10:54.3240942Z"} +{"id":"meshmind-14","title":"Introduce observability (logging, metrics) for ingestion and maintenance pipelines.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.376691886Z","updated_at":"2025-10-20T08:10:54.447013892Z","closed_at":"2025-10-20T08:10:54.447013892Z"} +{"id":"meshmind-15","title":"Promote the new README, archive the legacy version, and keep SOT diagrams/maps in sync.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.499831218Z","updated_at":"2025-10-20T08:10:54.567014858Z","closed_at":"2025-10-20T08:10:54.567014858Z"} +{"id":"meshmind-16","title":"Harden Celery maintenance tasks to initialize drivers lazily and persist consolidation results.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.616234297Z","updated_at":"2025-10-20T08:10:54.665278957Z","closed_at":"2025-10-20T08:10:54.665278957Z"} +{"id":"meshmind-17","title":"Replace constant importance scoring with a heuristic driven by token diversity, recency, metadata richness, and embedding magnitude.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.726972816Z","updated_at":"2025-10-20T08:10:54.775621101Z","closed_at":"2025-10-20T08:10:54.775621101Z"} +{"id":"meshmind-18","title":"Create fake Memgraph, Redis, and embedding drivers for testing purposes.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:54.895451768Z","updated_at":"2025-10-20T08:10:54.962723409Z","closed_at":"2025-10-20T08:10:54.962723409Z"} +{"id":"meshmind-19","title":"Expand `GraphDriver.list_entities` to support namespace/entity-label filters and propagate the behaviour through `MemoryManager`, graph retrieval wrappers, and the MeshMind client.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.024754158Z","updated_at":"2025-10-20T08:10:55.080708753Z","closed_at":"2025-10-20T08:10:55.080708753Z"} +{"id":"meshmind-2","title":"Add bootstrap helper for default encoder registration and call it from the CLI.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:52.92801016Z","updated_at":"2025-10-20T08:10:52.986384256Z","closed_at":"2025-10-20T08:10:52.986384256Z"} +{"id":"meshmind-20","title":"Extend REST/gRPC payloads, CLI helpers, and pytest coverage to exercise the new entity-label filtering semantics.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.139011558Z","updated_at":"2025-10-20T08:10:55.191979732Z","closed_at":"2025-10-20T08:10:55.191979732Z"} +{"id":"meshmind-21","title":"Stand up `docs/` wiki pages, `ENVIRONMENT_NEEDS.md`, and `RESUME_NOTES.md` so documentation and session hand-off stay current.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.251023288Z","updated_at":"2025-10-20T08:10:55.303866736Z","closed_at":"2025-10-20T08:10:55.303866736Z"} +{"id":"meshmind-22","title":"Add unit tests covering namespace/entity-label filtering for the SQLite driver and fake drivers.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.355597466Z","updated_at":"2025-10-20T08:10:55.4081723Z","closed_at":"2025-10-20T08:10:55.4081723Z"} +{"id":"meshmind-23","title":"Update the example pipeline (`examples/extract_preprocess_store_example.py`) to demonstrate entity-label restricted retrieval via the MeshMind client.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.475329588Z","updated_at":"2025-10-20T08:10:55.525258417Z","closed_at":"2025-10-20T08:10:55.525258417Z"} +{"id":"meshmind-24","title":"Document REST/gRPC request samples that include `entity_labels` in `docs/api.md`.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.581322468Z","updated_at":"2025-10-20T08:10:55.702355473Z","closed_at":"2025-10-20T08:10:55.702355473Z"} +{"id":"meshmind-25","title":"Add a regression test confirming `MeshMind.list_memories` forwards `entity_labels` to the memory manager.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.795922403Z","updated_at":"2025-10-20T08:10:55.856472417Z","closed_at":"2025-10-20T08:10:55.856472417Z"} +{"id":"meshmind-26","title":"Push graph-backed retrieval queries deeper into Memgraph/Neo4j backends so search executes without materializing entire namespaces.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:55.913665301Z","updated_at":"2025-10-20T08:10:55.970588738Z","closed_at":"2025-10-20T08:10:55.970588738Z"} +{"id":"meshmind-27","title":"Implement pagination/streaming options in `MemoryManager.list_memories` to avoid loading entire namespaces into memory.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.025766852Z","updated_at":"2025-10-20T08:10:56.080597902Z","closed_at":"2025-10-20T08:10:56.080597902Z"} +{"id":"meshmind-28","title":"Add CLI/admin command to report memory counts grouped by namespace and entity label for quick health checks.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.149469682Z","updated_at":"2025-10-20T08:10:56.206582302Z","closed_at":"2025-10-20T08:10:56.206582302Z"} +{"id":"meshmind-29","title":"Create developer tooling (pre-commit or CI check) that ensures `docs/` pages are touched when code under corresponding modules changes.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.265678269Z","updated_at":"2025-10-20T08:10:56.370709121Z","closed_at":"2025-10-20T08:10:56.370709121Z"} +{"id":"meshmind-3","title":"Update OpenAI encoder implementation to align with latest SDK responses and retry semantics.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.042028778Z","updated_at":"2025-10-20T08:10:53.095455761Z","closed_at":"2025-10-20T08:10:53.095455761Z"} +{"id":"meshmind-30","title":"Draft a troubleshooting section documenting optional tooling installation failures (ruff, pyright, typeguard, toml-sort, yamllint) and recommended fallbacks.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.426379495Z","updated_at":"2025-10-20T08:10:56.487904652Z","closed_at":"2025-10-20T08:10:56.487904652Z"} +{"id":"meshmind-31","title":"Expose `memory_counts` via the gRPC stub to keep service interfaces aligned.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.53828658Z","updated_at":"2025-10-20T08:10:56.592796107Z","closed_at":"2025-10-20T08:10:56.592796107Z"} +{"id":"meshmind-32","title":"Extend the docs guard mapping/tests so Docker, setup, and environment guides are enforced when related modules change.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.644967601Z","updated_at":"2025-10-20T08:10:56.697182628Z","closed_at":"2025-10-20T08:10:56.697182628Z"} +{"id":"meshmind-33","title":"Draft `CLEANUP.md` outlining post-restriction cleanups for files that were temporarily modified to satisfy sandbox limitations.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.747113272Z","updated_at":"2025-10-20T08:10:56.803109538Z","closed_at":"2025-10-20T08:10:56.803109538Z"} +{"id":"meshmind-34","title":"Audit the repository for direct `import openai` usage to scope the `llm_client` refactor.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:56.853948268Z","updated_at":"2025-10-20T08:10:56.981883325Z","closed_at":"2025-10-20T08:10:56.981883325Z"} +{"id":"meshmind-35","title":"Implement a provider-agnostic `meshmind/llm_client.py` wrapper that routes requests via configurable endpoint URLs.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.033129297Z","updated_at":"2025-10-20T08:10:57.088396465Z","closed_at":"2025-10-20T08:10:57.088396465Z"} +{"id":"meshmind-36","title":"Replace all direct OpenAI client interactions in the codebase with the new `llm_client` abstraction.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.140285112Z","updated_at":"2025-10-20T08:10:57.192315028Z","closed_at":"2025-10-20T08:10:57.192315028Z"} +{"id":"meshmind-37","title":"Update unit tests and documentation to reflect the `llm_client` usage pattern.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.256445371Z","updated_at":"2025-10-20T08:10:57.306852019Z","closed_at":"2025-10-20T08:10:57.306852019Z"} +{"id":"meshmind-38","title":"Extend configuration models to support per-operation LLM endpoint and model overrides with a default of `gpt-5-nano`.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.361680336Z","updated_at":"2025-10-20T08:10:57.42471403Z","closed_at":"2025-10-20T08:10:57.42471403Z"} +{"id":"meshmind-39","title":"Add CLI flags that override LLM endpoint/model settings when provided.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.481727815Z","updated_at":"2025-10-20T08:10:57.533663506Z","closed_at":"2025-10-20T08:10:57.533663506Z"} +{"id":"meshmind-4","title":"Improve configuration guidance and automation for environment variables and service setup.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.152112307Z","updated_at":"2025-10-20T08:10:53.215623612Z","closed_at":"2025-10-20T08:10:53.215623612Z"} +{"id":"meshmind-40","title":"Document the cascading LLM override behaviour across README and SETUP guides.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.586645728Z","updated_at":"2025-10-20T08:10:57.640606896Z","closed_at":"2025-10-20T08:10:57.640606896Z"} +{"id":"meshmind-41","title":"Expose LLM override fields via REST/gRPC payloads and verify they integrate with the `llm_client` abstraction.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.718535297Z","updated_at":"2025-10-20T08:10:57.770871964Z","closed_at":"2025-10-20T08:10:57.770871964Z"} +{"id":"meshmind-42","title":"Add API and service-level tests covering the new LLM override payloads once implemented.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.832884936Z","updated_at":"2025-10-20T08:10:57.885122926Z","closed_at":"2025-10-20T08:10:57.885122926Z"} +{"id":"meshmind-43","title":"Replace `datetime.utcnow()` usage in `meshmind/_compat/pydantic.py` with timezone-aware alternatives and update any tests relying on naive timestamps.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:57.936679697Z","updated_at":"2025-10-20T08:10:57.987666047Z","closed_at":"2025-10-20T08:10:57.987666047Z"} +{"id":"meshmind-44","title":"Add a smoke test or script check that `run/install_setup.sh` and `run/maintenance_setup.sh` install key optional packages (`neo4j`, `pymgclient`, `fastapi`) when internet access is present, documenting skip behaviour when offline.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.040386652Z","updated_at":"2025-10-20T08:10:58.098351599Z","closed_at":"2025-10-20T08:10:58.098351599Z"} +{"id":"meshmind-45","title":"Regenerate `uv.lock` to align with the updated dependency set (`fastapi`, `uvicorn`, `neo4j`, `pymgclient`, extras) once package downloads are possible (blocked: pip cannot access PyPI from this environment).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.156257904Z","updated_at":"2025-10-20T08:10:58.218692895Z","closed_at":"2025-10-20T08:10:58.218692895Z"} +{"id":"meshmind-46","title":"Document per-request LLM override payloads and CLI flags across `README.md`, `docs/api.md`, and `docs/configuration.md`.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.275787491Z","updated_at":"2025-10-20T08:10:58.341665963Z","closed_at":"2025-10-20T08:10:58.341665963Z"} +{"id":"meshmind-47","title":"Update `SETUP.md` and `docs/operations.md` to describe the provisioning scripts' validation step and skip environment variables.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.405244455Z","updated_at":"2025-10-20T08:10:58.459055014Z","closed_at":"2025-10-20T08:10:58.459055014Z"} +{"id":"meshmind-48","title":"Refresh `SOT.md`, `PLAN.md`, `PROJECT.md`, and `RECOMMENDATIONS.md` to capture the LLM override workflow and timezone-aware timestamp changes.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.512793857Z","updated_at":"2025-10-20T08:10:58.569068605Z","closed_at":"2025-10-20T08:10:58.569068605Z"} +{"id":"meshmind-49","title":"Extend `DUMMIES.md` and `docs/testing.md` with details about `FakeLLMClient` and the new setup script smoke test.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.719861655Z","updated_at":"2025-10-20T08:10:58.787171648Z","closed_at":"2025-10-20T08:10:58.787171648Z"} +{"id":"meshmind-5","title":"Wire `EntityRegistry` and `PredicateRegistry` into the storage pipeline and client.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.273145434Z","updated_at":"2025-10-20T08:10:53.329385935Z","closed_at":"2025-10-20T08:10:53.329385935Z"} +{"id":"meshmind-50","title":"Update `ENVIRONMENT_NEEDS.md` and `NEEDED_FOR_TESTING.md` to reflect the availability of optional packages (`fastapi`, `neo4j`, `pymgclient`, `uvicorn`).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.839918627Z","updated_at":"2025-10-20T08:10:58.895955398Z","closed_at":"2025-10-20T08:10:58.895955398Z"} +{"id":"meshmind-51","title":"Draft `ROADMAP.md` documenting short-, mid-, and long-term milestones extracted from the latest planning docs.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:58.946394868Z","updated_at":"2025-10-20T08:10:59.001128453Z","closed_at":"2025-10-20T08:10:59.001128453Z"} +{"id":"meshmind-52","title":"Capture architectural strategy questions in `PLANNING_THOUGHTS.md` to preserve current decision rationale.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.054137217Z","updated_at":"2025-10-20T08:10:59.112282213Z","closed_at":"2025-10-20T08:10:59.112282213Z"} +{"id":"meshmind-53","title":"Assemble a `research/` knowledge base summarising competitor capabilities and research references.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.201278541Z","updated_at":"2025-10-20T08:10:59.430645702Z","closed_at":"2025-10-20T08:10:59.430645702Z"} +{"id":"meshmind-54","title":"Implement and document maintenance retry/backoff semantics across `meshmind/tasks/scheduled.py`, configuration, and supporting docs/tests.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.485079057Z","updated_at":"2025-10-20T08:10:59.546513033Z","closed_at":"2025-10-20T08:10:59.546513033Z"} +{"id":"meshmind-55","title":"Add REST and CLI smoke tests covering `/memories/counts` so docs and examples stay executable with the in-memory driver.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.601243019Z","updated_at":"2025-10-20T08:10:59.654020719Z","closed_at":"2025-10-20T08:10:59.654020719Z"} +{"id":"meshmind-56","title":"Validate consolidation heuristics on larger datasets to confirm accuracy and stability under load.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.706495433Z","updated_at":"2025-10-20T08:10:59.764627482Z","closed_at":"2025-10-20T08:10:59.764627482Z"} +{"id":"meshmind-57","title":"Establish evaluation loops (analytics or LLM-assisted) to tune the new importance heuristic over time (initial synthetic benchmarking scripts in place).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.836297181Z","updated_at":"2025-10-20T08:10:59.906013533Z","closed_at":"2025-10-20T08:10:59.906013533Z"} +{"id":"meshmind-58","title":"Replace the compatibility shim with production Pydantic models once upstream packaging supports the target Python versions.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:59.962152787Z","updated_at":"2025-10-20T08:11:00.01880631Z","closed_at":"2025-10-20T08:11:00.01880631Z"} +{"id":"meshmind-59","title":"Verify curl/grpcurl snippets against running REST/gRPC services once infrastructure is available (FastAPI TestClient + gRPC stub coverage).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.072672636Z","updated_at":"2025-10-20T08:11:00.132307598Z","closed_at":"2025-10-20T08:11:00.132307598Z"} +{"id":"meshmind-6","title":"Implement CRUD and triplet methods on `MeshMind`, including relationship persistence in `GraphDriver`.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.383984265Z","updated_at":"2025-10-20T08:10:53.499686605Z","closed_at":"2025-10-20T08:10:53.499686605Z"} +{"id":"meshmind-60","title":"Add CLI flags for maintenance retry overrides so operators can tune `MAINTENANCE_MAX_ATTEMPTS`/`MAINTENANCE_BASE_DELAY_SECONDS` per run.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.227159417Z","updated_at":"2025-10-20T08:11:00.283747749Z","closed_at":"2025-10-20T08:11:00.283747749Z"} +{"id":"meshmind-61","title":"Benchmark driver-side pagination/filtering on large datasets to tune default candidate limits and document recommended overrides (synthetic benchmarks implemented).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.336969934Z","updated_at":"2025-10-20T08:11:00.399034131Z","closed_at":"2025-10-20T08:11:00.399034131Z"} +{"id":"meshmind-62","title":"Create a synthetic consolidation benchmark script that logs retry telemetry snapshots for analysis.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.464626339Z","updated_at":"2025-10-20T08:11:00.520798324Z","closed_at":"2025-10-20T08:11:00.520798324Z"} +{"id":"meshmind-63","title":"Generate protobuf definitions for the gRPC service (`meshmind/protos/memory_service.proto`) and refactor `meshmind.api.grpc` to use the canonical schema.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.574749328Z","updated_at":"2025-10-20T08:11:00.626012554Z","closed_at":"2025-10-20T08:11:00.626012554Z"} +{"id":"meshmind-64","title":"Update REST/gRPC documentation and tests (`README.md`, `docs/api.md`, `docs/testing.md`, `meshmind/tests/test_service_interfaces.py`, `meshmind/tests/test_api_examples.py`) to reflect the protobuf-backed interface.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.672348837Z","updated_at":"2025-10-20T08:11:00.723666057Z","closed_at":"2025-10-20T08:11:00.723666057Z"} +{"id":"meshmind-65","title":"Add a `make benchmarks` target that runs the synthetic benchmarking scripts and documents the workflow across README and docs.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.780831142Z","updated_at":"2025-10-20T08:11:00.834534084Z","closed_at":"2025-10-20T08:11:00.834534084Z"} +{"id":"meshmind-66","title":"Regenerate `uv.lock` after installing gRPC tooling and optional dependencies when network and permissions allow.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:00.886407074Z","updated_at":"2025-10-20T08:11:00.981696875Z","closed_at":"2025-10-20T08:11:00.981696875Z"} +{"id":"meshmind-67","title":"Implement asyncio gRPC server helpers (`meshmind.api.grpc_server`) and smoke tests covering ingestion/search and lifecycle cancellation.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.057232198Z","updated_at":"2025-10-20T08:11:01.113267585Z","closed_at":"2025-10-20T08:11:01.113267585Z"} +{"id":"meshmind-68","title":"Add packaging tests to guarantee `meshmind/protos/memory_service.proto` ships with the distribution and exposes the expected service definition.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.165003787Z","updated_at":"2025-10-20T08:11:01.227818676Z","closed_at":"2025-10-20T08:11:01.227818676Z"} +{"id":"meshmind-69","title":"Document runtime and operational guidance for the gRPC server across README, SETUP, `docs/api.md`, and `docs/operations.md`.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.279237658Z","updated_at":"2025-10-20T08:11:01.331840038Z","closed_at":"2025-10-20T08:11:01.331840038Z"} +{"id":"meshmind-7","title":"Refresh examples to cover relationship-aware ingestion and retrieval flows.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.56023522Z","updated_at":"2025-10-20T08:10:53.624207493Z","closed_at":"2025-10-20T08:10:53.624207493Z"} +{"id":"meshmind-70","title":"Add Makefile and CI targets (`make protos`, `make protos-check`) plus scripts to regenerate/verify protobuf bindings, failing CI when drift occurs.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.379873545Z","updated_at":"2025-10-20T08:11:01.434951664Z","closed_at":"2025-10-20T08:11:01.434951664Z"} +{"id":"meshmind-71","title":"Replace the REST stub with the concrete FastAPI application and migrate smoke tests to `fastapi.testclient.TestClient`.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.487143894Z","updated_at":"2025-10-20T08:11:01.541889547Z","closed_at":"2025-10-20T08:11:01.541889547Z"} +{"id":"meshmind-72","title":"Remove Celery dummy fallbacks by requiring the real app/beat imports and keeping docker-compose stacks in sync.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.595777816Z","updated_at":"2025-10-20T08:11:01.649505792Z","closed_at":"2025-10-20T08:11:01.649505792Z"} +{"id":"meshmind-73","title":"Add a `serve-grpc` CLI subcommand and verify it delegates to the runtime helpers.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.698731826Z","updated_at":"2025-10-20T08:11:01.830918043Z","closed_at":"2025-10-20T08:11:01.830918043Z"} +{"id":"meshmind-74","title":"Teach docker-compose stacks (root and `meshmind/tests/docker/full-stack.yml`) to launch the gRPC service via the new CLI entry point.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:01.883995397Z","updated_at":"2025-10-20T08:11:01.949062705Z","closed_at":"2025-10-20T08:11:01.949062705Z"} +{"id":"meshmind-75","title":"Add pytest coverage for `scripts/check_protos.py` so protobuf drift detection stays exercised.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.008690847Z","updated_at":"2025-10-20T08:11:02.066044567Z","closed_at":"2025-10-20T08:11:02.066044567Z"} +{"id":"meshmind-76","title":"Expand the documentation guard mapping to require API/operations updates when CLI modules change.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.115190419Z","updated_at":"2025-10-20T08:11:02.163871672Z","closed_at":"2025-10-20T08:11:02.163871672Z"} +{"id":"meshmind-77","title":"Validate Neo4j driver requirements and connectivity against a live cluster (integration suite exercises docker-compose services).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.227042111Z","updated_at":"2025-10-20T08:11:02.294602405Z","closed_at":"2025-10-20T08:11:02.294602405Z"} +{"id":"meshmind-78","title":"Provision Neo4j, Memgraph, and Redis instances accessible from the development environment to unblock live integration tests (documented via docker-compose).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.346669378Z","updated_at":"2025-10-20T08:11:02.400093311Z","closed_at":"2025-10-20T08:11:02.400093311Z"} +{"id":"meshmind-79","title":"Approve and install optional dependencies (`neo4j`, `pymgclient`, `redis`, `celery`, `tiktoken`, `sentence-transformers`) across CI and developer machines to exercise full workflows (standardised on `uv sync --all-extras`).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.457629565Z","updated_at":"2025-10-20T08:11:02.521125043Z","closed_at":"2025-10-20T08:11:02.521125043Z"} +{"id":"meshmind-8","title":"Extend retrieval module with vector-only, regex, exact-match, and optional LLM rerank search helpers.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.678276547Z","updated_at":"2025-10-20T08:10:53.735819853Z","closed_at":"2025-10-20T08:10:53.735819853Z"} +{"id":"meshmind-80","title":"Source or generate large synthetic datasets for consolidation and retrieval benchmarking to validate heuristics under load (`scripts/generate_synthetic_dataset.py`).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.617574155Z","updated_at":"2025-10-20T08:11:02.671725264Z","closed_at":"2025-10-20T08:11:02.671725264Z"} +{"id":"meshmind-81","title":"Define and ratify a policy for reintroducing Pydantic models (version targets, rollout timeline) so compatibility shims remain unnecessary going forward (documented in `docs/development.md`).","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:11:02.721334743Z","updated_at":"2025-10-20T08:11:02.794824822Z","closed_at":"2025-10-20T08:11:02.794824822Z"} +{"id":"meshmind-82","title":"Implement backend-native vector similarity queries for Memgraph/Neo4j to eliminate Python-side scoring when embeddings are present.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:02.862398659Z","updated_at":"2025-10-20T08:11:02.862398659Z"} +{"id":"meshmind-83","title":"Run `scripts/consolidation_benchmark.py` against a ≥10k-memory dataset and document recommended retry defaults in `README.md` and `ENVIRONMENT_NEEDS.md`.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:02.918005653Z","updated_at":"2025-10-20T08:11:02.918005653Z"} +{"id":"meshmind-84","title":"Run `scripts/benchmark_pagination.py` against live Memgraph/Neo4j instances to tune default pagination limits and capture guidance in `docs/retrieval.md`.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:02.988242617Z","updated_at":"2025-10-20T08:11:02.988242617Z"} +{"id":"meshmind-85","title":"Implement integration tests exercising `meshmind admin maintenance --max-attempts/--base-delay` with a real Celery worker and Redis once infrastructure is available.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.053155593Z","updated_at":"2025-10-20T08:11:03.053155593Z"} +{"id":"meshmind-86","title":"Validate the documented curl/grpcurl snippets against deployed REST/gRPC services (with auth) once staging environments are reachable.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.113860491Z","updated_at":"2025-10-20T08:11:03.113860491Z"} +{"id":"meshmind-87","title":"Add integration tests that spin up `meshmind serve-grpc` and exercise ingestion/search via grpcurl to complement the unit-level coverage (blocked until network-accessible infrastructure is ready).","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.176082109Z","updated_at":"2025-10-20T08:11:03.176082109Z"} +{"id":"meshmind-88","title":"Publish protobuf-generated client artifacts (Python wheel or language-neutral bundles) so external services can consume the API once infrastructure is available.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.26586552Z","updated_at":"2025-10-20T08:11:03.26586552Z"} +{"id":"meshmind-89","title":"Automate the live integration suite (`pytest -m integration`) in CI so Memgraph/Neo4j/Redis regressions fail fast.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.364308443Z","updated_at":"2025-10-20T08:11:03.364308443Z"} +{"id":"meshmind-9","title":"Modernize pytest suites and add fixtures to run without external services.","description":"Imported from TODO.md (Completed section).","status":"closed","priority":3,"issue_type":"task","created_at":"2025-10-20T08:10:53.789057117Z","updated_at":"2025-10-20T08:10:53.866210561Z","closed_at":"2025-10-20T08:10:53.866210561Z"} +{"id":"meshmind-90","title":"Document ingestion workflows for the synthetic dataset generator across `docs/retrieval.md` and operations guides so benchmarking instructions stay cohesive.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.472955548Z","updated_at":"2025-10-20T08:11:03.472955548Z"} +{"id":"meshmind-91","title":"Document the retired REST/Celery shims in release notes and communicate migration steps to downstream integrators.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.60118748Z","updated_at":"2025-10-20T08:11:03.60118748Z"} +{"id":"meshmind-92","title":"Capture gRPC CLI usage examples (including docker-compose orchestration) in `docs/api.md` and `docs/operations.md` once integration smoke tests complete.","description":"Imported from TODO.md (Priority Tasks section).","status":"open","priority":0,"issue_type":"task","created_at":"2025-10-20T08:11:03.663147668Z","updated_at":"2025-10-20T08:11:03.663147668Z"} +{"id":"meshmind-93","title":"Identify candidate observability exporters (Prometheus/OpenTelemetry) and draft rollout steps for external telemetry sinks.","description":"Imported from TODO.md (Recommended Waiting for Approval Tasks section).","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-20T08:11:03.803775731Z","updated_at":"2025-10-20T08:11:03.803775731Z"} +{"id":"meshmind-94","title":"Explore UI concepts for inspecting memories/triplets once the API hardening tasks land.","description":"Imported from TODO.md (Recommended Waiting for Approval Tasks section).","status":"open","priority":2,"issue_type":"task","created_at":"2025-10-20T08:11:03.86471906Z","updated_at":"2025-10-20T08:11:03.86471906Z"} diff --git a/AGENTS.md b/AGENTS.md index 09ebc4c..c699e1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,20 +1,106 @@ # Agent Instructions +## Issue Tracking with Beads +- Use the `bd` Beads CLI for all issue, task, and dependency tracking in this repository. +- Initialize the tracker with `bd init` if the `.beads/` database is missing, and commit the resulting files. +- When you discover new work, blockers, or follow-ups while coding, immediately create a Beads issue before continuing the task at hand. +- Keep issue metadata accurate: set priorities, statuses, and dependency edges (`blocks`, `related`, `parent-child`, `discovered-from`) so the ready queue always reflects the next actionable work. +- Review available work with `bd ready`/`bd list` at the start of each session, and close or update issues as soon as the underlying work lands. + ## Documentation Workflow -- After each batch of changes, add a `CHANGELOG.md` entry with an ISO 8601 date/time stamp in United States Eastern time (include the timezone code, e.g., `America/New_York` or `ET`) and developer-facing detail (files, modules, functions, variables, and rationale). Every commit should correspond to a fresh entry. +- After each batch of changes, add a `CHANGELOG.md` entry with an ISO 8601 timestamp in United States Eastern time (e.g., `America/New_York`) summarising developer-facing details and rationale. - Maintain `README.md` as the canonical description of the project; update it whenever behaviour or workflows change. Archive older versions separately when requested. -- Keep the `docs/` wiki and provisioning guides (`SETUP.md`, `ENVIRONMENT_NEEDS.md`) in sync with code updates; add or revise the - relevant page whenever features, modules, or workflows change. -- After each iteration, refresh `ISSUES.md`, `SOT.md`, `PLAN.md`, `RECOMMENDATIONS.md`, `TODO.md`, and related documentation to stay in sync with the codebase. -- Ensure `TODO.md` retains the `Completed`, `Priority Tasks`, and `Recommended Waiting for Approval Tasks` sections, moving finished items under `Completed` at the end of every turn. -- Make every task in `TODO.md` atomic: each entry must describe a single, self-contained deliverable with enough detail to execute and verify without cross-referencing additional context. +- Keep the `docs/` wiki and provisioning guides (`SETUP.md`, `ENVIRONMENT_NEEDS.md`) in sync with code updates; revise the relevant page whenever features, modules, or workflows change. +- After each iteration, refresh `ISSUES.md`, `SOT.md`, `PLAN.md`, and `RECOMMENDATIONS.md` so they stay aligned with the current state of the codebase and Beads issue tracker. - Update `RESUME_NOTES.md` at the end of every turn so the next session starts with accurate context. -- When beginning a turn, review `README.md`, `PROJECT.md`, `PLAN.md`, `RECOMMENDATIONS.md`, `ISSUES.md`, `SOT.md`, `ROADMAP.md`, `PLANNING_THOUGHTS.md`, and the `research/` wiki to harvest new actionable work. Maintain at least ten quantifiable, prioritised items in the `Priority Tasks` section of `TODO.md`, adding context or links when needed. +- When beginning a turn, review `README.md`, `PROJECT.md`, `PLAN.md`, `RECOMMENDATIONS.md`, `ISSUES.md`, `SOT.md`, `ROADMAP.md`, `PLANNING_THOUGHTS.md`, the `research/` wiki, and the open Beads issues to harvest actionable work. - Keep `ROADMAP.md`, `PLANNING_THOUGHTS.md`, and the `research/` docs aligned with each iteration when new discoveries or decisions occur. -- After completing any task, immediately update `TODO.md`, check for the next actionable item, and continue iterating until all unblocked `Priority Tasks` are exhausted for the session. -- Continuously loop through planning and execution: finish a task, document it, surface new follow-ups, and resume implementation so long as environment blockers allow. If extra guidance would improve throughput, extend these instructions proactively. +- Continuously loop through planning and execution: finish a task, document it, surface new follow-ups as Beads issues, and resume implementation while unblocked work remains. ## Style Guidelines - Use descriptive Markdown headings starting at level 1 for top-level documents. - Keep lines to 120 characters or fewer when practical. - Prefer bullet lists for enumerations instead of inline commas. + +## bd quickstart reference output +``` +bd - Dependency-Aware Issue Tracker + +Issues chained together like beads. + +GETTING STARTED + bd init Initialize bd in your project + Creates .beads/ directory with project-specific database + Auto-detects prefix from directory name (e.g., myapp-1, myapp-2) + + bd init --prefix api Initialize with custom prefix + Issues will be named: api-1, api-2, ... + +CREATING ISSUES + bd create "Fix login bug" + bd create "Add auth" -p 0 -t feature + bd create "Write tests" -d "Unit tests for auth" --assignee alice + +VIEWING ISSUES + bd list List all issues + bd list --status open List by status + bd list --priority 0 List by priority (0-4, 0=highest) + bd show bd-1 Show issue details + +MANAGING DEPENDENCIES + bd dep add bd-1 bd-2 Add dependency (bd-2 blocks bd-1) + bd dep tree bd-1 Visualize dependency tree + bd dep cycles Detect circular dependencies + +DEPENDENCY TYPES + blocks Task B must complete before task A + related Soft connection, doesn't block progress + parent-child Epic/subtask hierarchical relationship + discovered-from Auto-created when AI discovers related work + +READY WORK + bd ready Show issues ready to work on + Ready = status is 'open' AND no blocking dependencies + Perfect for agents to claim next work! + +UPDATING ISSUES + bd update bd-1 --status in_progress + bd update bd-1 --priority 0 + bd update bd-1 --assignee bob + +CLOSING ISSUES + bd close bd-1 + bd close bd-2 bd-3 --reason "Fixed in PR #42" + +DATABASE LOCATION + bd automatically discovers your database: + 1. --db /path/to/db.db flag + 2. $BEADS_DB environment variable + 3. .beads/*.db in current directory or ancestors + 4. ~/.beads/default.db as fallback + +AGENT INTEGRATION + bd is designed for AI-supervised workflows: + • Agents create issues when discovering new work + • bd ready shows unblocked work ready to claim + • Use --json flags for programmatic parsing + • Dependencies prevent agents from duplicating effort + +DATABASE EXTENSION + Applications can extend bd's SQLite database: + • Add your own tables (e.g., myapp_executions) + • Join with issues table for powerful queries + • See database extension docs for integration patterns: + https://github.com/steveyegge/beads/blob/main/EXTENDING.md + +GIT WORKFLOW (AUTO-SYNC) + bd automatically keeps git in sync: + • ✓ Export to JSONL after CRUD operations (5s debounce) + • ✓ Import from JSONL when newer than DB (after git pull) + • ✓ Works seamlessly across machines and team members + • No manual export/import needed! + Disable with: --no-auto-flush or --no-auto-import + +Ready to start! +Run bd create "My first issue" to create your first issue. +``` diff --git a/CHANGELOG.md b/CHANGELOG.md index a676740..9ae63b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## [2025-10-20T04:12:44-04:00 (America/New_York)] +### Added +- Introduced `.beads/` project database and exported Beads issue JSONL by initializing bd and migrating existing TODO items. +- Added `reference-docs/` snapshots of upstream Beads documentation (`Beads-*.md`) for local reference. + +### Changed +- Rewrote `AGENTS.md` to mandate Beads-based workflow and appended the `bd quickstart` reference output; simplified `TODO.md` to delegate planning to bd. +- Imported every task from the legacy `TODO.md` into the Beads tracker with appropriate open/closed status and added an `ISSUES.md` note pointing contributors to bd commands. + ## [2025-10-16T20:39:06-04:00 (America/New_York)] ### Added - Added live integration coverage for Memgraph, Neo4j, and Redis via `meshmind/tests/test_integration_live.py` and configured diff --git a/ISSUES.md b/ISSUES.md index db7bf9b..c60a924 100644 --- a/ISSUES.md +++ b/ISSUES.md @@ -1,5 +1,8 @@ # Issues Checklist +> [!NOTE] +> Issue and task tracking now lives in the Beads issue tracker (`bd`). Use `bd list`, `bd show `, and `bd ready` for the live source of truth; the checklists below remain as historical context. + ## Blockers - [x] MeshMind client fails without the `mgclient` module; introduce lazy driver initialization or documented in-memory fallback. - [x] Register a default embedding encoder (OpenAI or sentence-transformers) during startup so extraction and hybrid search can run. @@ -38,4 +41,4 @@ - [x] Offer alternative storage backends (in-memory driver, SQLite, etc.) for easier local development. - [x] Provide an administrative dashboard or CLI commands for listing namespaces, counts, and maintenance statistics (CLI admin subcommands now expose predicates, telemetry, and graph checks). - [ ] Publish onboarding guides and troubleshooting FAQs for contributors. -- [ ] Explore plugin registration for embeddings and retrieval strategies to reduce manual wiring. +- [ ] Explore plugin registration for embeddings and retrieval strategies to reduce manual wiring. \ No newline at end of file diff --git a/TODO.md b/TODO.md index 6bd8279..cec882c 100644 --- a/TODO.md +++ b/TODO.md @@ -1,105 +1,5 @@ # TODO -## Completed +All project planning and task tracking now lives in the Beads issue tracker. Use the `bd` CLI (e.g., `bd ready`, `bd list --status open`, `bd show `) to review open work, and record any new discoveries as Beads issues immediately. -- [x] Implement dependency guards and lazy imports for optional packages (`pymgclient`, `tiktoken`, `celery`, `sentence-transformers`). -- [x] Add bootstrap helper for default encoder registration and call it from the CLI. -- [x] Update OpenAI encoder implementation to align with latest SDK responses and retry semantics. -- [x] Improve configuration guidance and automation for environment variables and service setup. -- [x] Wire `EntityRegistry` and `PredicateRegistry` into the storage pipeline and client. -- [x] Implement CRUD and triplet methods on `MeshMind`, including relationship persistence in `GraphDriver`. -- [x] Refresh examples to cover relationship-aware ingestion and retrieval flows. -- [x] Extend retrieval module with vector-only, regex, exact-match, and optional LLM rerank search helpers. -- [x] Modernize pytest suites and add fixtures to run without external services. -- [x] Expand Makefile and add CI workflows for linting, testing, and type checks. -- [x] Document or provision local Memgraph and Redis services (e.g., via docker-compose) for onboarding. -- [x] Abstract `GraphDriver` to support alternative storage backends (Neo4j, in-memory, SQLite prototype). -- [x] Add service interfaces (REST/gRPC) for ingestion and retrieval. -- [x] Introduce observability (logging, metrics) for ingestion and maintenance pipelines. -- [x] Promote the new README, archive the legacy version, and keep SOT diagrams/maps in sync. -- [x] Harden Celery maintenance tasks to initialize drivers lazily and persist consolidation results. -- [x] Replace constant importance scoring with a heuristic driven by token diversity, recency, metadata richness, and embedding magnitude. -- [x] Create fake Memgraph, Redis, and embedding drivers for testing purposes. -- [x] Expand `GraphDriver.list_entities` to support namespace/entity-label filters and propagate the behaviour through `MemoryManager`, graph retrieval wrappers, and the MeshMind client. -- [x] Extend REST/gRPC payloads, CLI helpers, and pytest coverage to exercise the new entity-label filtering semantics. -- [x] Stand up `docs/` wiki pages, `ENVIRONMENT_NEEDS.md`, and `RESUME_NOTES.md` so documentation and session hand-off stay current. -- [x] Add unit tests covering namespace/entity-label filtering for the SQLite driver and fake drivers. -- [x] Update the example pipeline (`examples/extract_preprocess_store_example.py`) to demonstrate entity-label restricted retrieval via the MeshMind client. -- [x] Document REST/gRPC request samples that include `entity_labels` in `docs/api.md`. -- [x] Add a regression test confirming `MeshMind.list_memories` forwards `entity_labels` to the memory manager. -- [x] Push graph-backed retrieval queries deeper into Memgraph/Neo4j backends so search executes without materializing entire namespaces. -- [x] Implement pagination/streaming options in `MemoryManager.list_memories` to avoid loading entire namespaces into memory. -- [x] Add CLI/admin command to report memory counts grouped by namespace and entity label for quick health checks. -- [x] Create developer tooling (pre-commit or CI check) that ensures `docs/` pages are touched when code under corresponding modules changes. -- [x] Draft a troubleshooting section documenting optional tooling installation failures (ruff, pyright, typeguard, toml-sort, yamllint) and recommended fallbacks. -- [x] Expose `memory_counts` via the gRPC stub to keep service interfaces aligned. - -- [x] Extend the docs guard mapping/tests so Docker, setup, and environment guides are enforced when related modules change. -- [x] Draft `CLEANUP.md` outlining post-restriction cleanups for files that were temporarily modified to satisfy sandbox limitations. -- [x] Audit the repository for direct `import openai` usage to scope the `llm_client` refactor. -- [x] Implement a provider-agnostic `meshmind/llm_client.py` wrapper that routes requests via configurable endpoint URLs. -- [x] Replace all direct OpenAI client interactions in the codebase with the new `llm_client` abstraction. -- [x] Update unit tests and documentation to reflect the `llm_client` usage pattern. -- [x] Extend configuration models to support per-operation LLM endpoint and model overrides with a default of `gpt-5-nano`. -- [x] Add CLI flags that override LLM endpoint/model settings when provided. -- [x] Document the cascading LLM override behaviour across README and SETUP guides. -- [x] Expose LLM override fields via REST/gRPC payloads and verify they integrate with the `llm_client` abstraction. -- [x] Add API and service-level tests covering the new LLM override payloads once implemented. -- [x] Replace `datetime.utcnow()` usage in `meshmind/_compat/pydantic.py` with timezone-aware alternatives and update any tests relying on naive timestamps. -- [x] Add a smoke test or script check that `run/install_setup.sh` and `run/maintenance_setup.sh` install key optional packages (`neo4j`, `pymgclient`, `fastapi`) when internet access is present, documenting skip behaviour when offline. -- [x] Regenerate `uv.lock` to align with the updated dependency set (`fastapi`, `uvicorn`, `neo4j`, `pymgclient`, extras) once package downloads are possible (blocked: pip cannot access PyPI from this environment). -- [x] Document per-request LLM override payloads and CLI flags across `README.md`, `docs/api.md`, and `docs/configuration.md`. -- [x] Update `SETUP.md` and `docs/operations.md` to describe the provisioning scripts' validation step and skip environment variables. -- [x] Refresh `SOT.md`, `PLAN.md`, `PROJECT.md`, and `RECOMMENDATIONS.md` to capture the LLM override workflow and timezone-aware timestamp changes. -- [x] Extend `DUMMIES.md` and `docs/testing.md` with details about `FakeLLMClient` and the new setup script smoke test. -- [x] Update `ENVIRONMENT_NEEDS.md` and `NEEDED_FOR_TESTING.md` to reflect the availability of optional packages (`fastapi`, `neo4j`, `pymgclient`, `uvicorn`). -- [x] Draft `ROADMAP.md` documenting short-, mid-, and long-term milestones extracted from the latest planning docs. -- [x] Capture architectural strategy questions in `PLANNING_THOUGHTS.md` to preserve current decision rationale. -- [x] Assemble a `research/` knowledge base summarising competitor capabilities and research references. -- [x] Implement and document maintenance retry/backoff semantics across `meshmind/tasks/scheduled.py`, configuration, and supporting docs/tests. -- [x] Add REST and CLI smoke tests covering `/memories/counts` so docs and examples stay executable with the in-memory driver. -- [x] Validate consolidation heuristics on larger datasets to confirm accuracy and stability under load. -- [x] Establish evaluation loops (analytics or LLM-assisted) to tune the new importance heuristic over time (initial synthetic benchmarking scripts in place). -- [x] Replace the compatibility shim with production Pydantic models once upstream packaging supports the target Python versions. -- [x] Verify curl/grpcurl snippets against running REST/gRPC services once infrastructure is available (FastAPI TestClient + gRPC stub coverage). -- [x] Add CLI flags for maintenance retry overrides so operators can tune `MAINTENANCE_MAX_ATTEMPTS`/`MAINTENANCE_BASE_DELAY_SECONDS` per run. -- [x] Benchmark driver-side pagination/filtering on large datasets to tune default candidate limits and document recommended overrides (synthetic benchmarks implemented). -- [x] Create a synthetic consolidation benchmark script that logs retry telemetry snapshots for analysis. -- [x] Generate protobuf definitions for the gRPC service (`meshmind/protos/memory_service.proto`) and refactor `meshmind.api.grpc` to use the canonical schema. -- [x] Update REST/gRPC documentation and tests (`README.md`, `docs/api.md`, `docs/testing.md`, `meshmind/tests/test_service_interfaces.py`, `meshmind/tests/test_api_examples.py`) to reflect the protobuf-backed interface. -- [x] Add a `make benchmarks` target that runs the synthetic benchmarking scripts and documents the workflow across README and docs. -- [x] Regenerate `uv.lock` after installing gRPC tooling and optional dependencies when network and permissions allow. -- [x] Implement asyncio gRPC server helpers (`meshmind.api.grpc_server`) and smoke tests covering ingestion/search and lifecycle cancellation. -- [x] Add packaging tests to guarantee `meshmind/protos/memory_service.proto` ships with the distribution and exposes the expected service definition. -- [x] Document runtime and operational guidance for the gRPC server across README, SETUP, `docs/api.md`, and `docs/operations.md`. -- [x] Add Makefile and CI targets (`make protos`, `make protos-check`) plus scripts to regenerate/verify protobuf bindings, failing CI when drift occurs. -- [x] Replace the REST stub with the concrete FastAPI application and migrate smoke tests to `fastapi.testclient.TestClient`. -- [x] Remove Celery dummy fallbacks by requiring the real app/beat imports and keeping docker-compose stacks in sync. -- [x] Add a `serve-grpc` CLI subcommand and verify it delegates to the runtime helpers. -- [x] Teach docker-compose stacks (root and `meshmind/tests/docker/full-stack.yml`) to launch the gRPC service via the new CLI entry point. -- [x] Add pytest coverage for `scripts/check_protos.py` so protobuf drift detection stays exercised. -- [x] Expand the documentation guard mapping to require API/operations updates when CLI modules change. -- [x] Validate Neo4j driver requirements and connectivity against a live cluster (integration suite exercises docker-compose services). -- [x] Provision Neo4j, Memgraph, and Redis instances accessible from the development environment to unblock live integration tests (documented via docker-compose). -- [x] Approve and install optional dependencies (`neo4j`, `pymgclient`, `redis`, `celery`, `tiktoken`, `sentence-transformers`) across CI and developer machines to exercise full workflows (standardised on `uv sync --all-extras`). -- [x] Source or generate large synthetic datasets for consolidation and retrieval benchmarking to validate heuristics under load (`scripts/generate_synthetic_dataset.py`). -- [x] Define and ratify a policy for reintroducing Pydantic models (version targets, rollout timeline) so compatibility shims remain unnecessary going forward (documented in `docs/development.md`). - -## Priority Tasks - -- [ ] Implement backend-native vector similarity queries for Memgraph/Neo4j to eliminate Python-side scoring when embeddings are present. -- [ ] Run `scripts/consolidation_benchmark.py` against a ≥10k-memory dataset and document recommended retry defaults in `README.md` and `ENVIRONMENT_NEEDS.md`. -- [ ] Run `scripts/benchmark_pagination.py` against live Memgraph/Neo4j instances to tune default pagination limits and capture guidance in `docs/retrieval.md`. -- [ ] Implement integration tests exercising `meshmind admin maintenance --max-attempts/--base-delay` with a real Celery worker and Redis once infrastructure is available. -- [ ] Validate the documented curl/grpcurl snippets against deployed REST/gRPC services (with auth) once staging environments are reachable. -- [ ] Add integration tests that spin up `meshmind serve-grpc` and exercise ingestion/search via grpcurl to complement the unit-level coverage (blocked until network-accessible infrastructure is ready). -- [ ] Publish protobuf-generated client artifacts (Python wheel or language-neutral bundles) so external services can consume the API once infrastructure is available. -- [ ] Automate the live integration suite (`pytest -m integration`) in CI so Memgraph/Neo4j/Redis regressions fail fast. -- [ ] Document ingestion workflows for the synthetic dataset generator across `docs/retrieval.md` and operations guides so benchmarking instructions stay cohesive. -- [ ] Document the retired REST/Celery shims in release notes and communicate migration steps to downstream integrators. -- [ ] Capture gRPC CLI usage examples (including docker-compose orchestration) in `docs/api.md` and `docs/operations.md` once integration smoke tests complete. - -## Recommended Waiting for Approval Tasks - -- [ ] Identify candidate observability exporters (Prometheus/OpenTelemetry) and draft rollout steps for external telemetry sinks. -- [ ] Explore UI concepts for inspecting memories/triplets once the API hardening tasks land. +Historical tasks from the prior markdown list have been imported into Beads with their original completion statuses for reference. diff --git a/reference-docs/Beads-AGENTS.md b/reference-docs/Beads-AGENTS.md new file mode 100644 index 0000000..16f2fb2 --- /dev/null +++ b/reference-docs/Beads-AGENTS.md @@ -0,0 +1,449 @@ +# Instructions for AI Agents Working on Beads + +## Project Overview + +This is **beads** (command: `bd`), an issue tracker designed for AI-supervised coding workflows. We dogfood our own tool! + +## Issue Tracking + +We use bd (beads) for issue tracking instead of Markdown TODOs or external tools. + +### MCP Server (Recommended) + +**RECOMMENDED**: Use the MCP (Model Context Protocol) server for the best experience! The beads MCP server provides native integration with Claude and other MCP-compatible AI assistants. + +**Installation:** +```bash +# Install the MCP server +pip install beads-mcp + +# Add to your MCP settings (e.g., Claude Desktop config) +{ + "beads": { + "command": "beads-mcp", + "args": [] + } +} +``` + +**Benefits:** +- Native function calls instead of shell commands +- Automatic workspace detection +- Better error handling and validation +- Structured JSON responses +- No need for `--json` flags + +**All bd commands are available as MCP functions** with the prefix `mcp__beads-*__`. For example: +- `bd ready` → `mcp__beads__ready()` +- `bd create` → `mcp__beads__create(title="...", priority=1)` +- `bd update` → `mcp__beads__update(issue_id="bd-42", status="in_progress")` + +See `integrations/beads-mcp/README.md` for complete documentation. + +### Multi-Repo Configuration (MCP Server) + +**RECOMMENDED: Use a single MCP server with global daemon** for all beads repositories. + +**Setup (one-time):** +```bash +# Start global daemon (or it will auto-start on first bd command) +bd daemon --global + +# MCP config in ~/.config/amp/settings.json or Claude Desktop config: +{ + "beads": { + "command": "beads-mcp", + "args": [] + } +} +``` + +**How it works:** +The single MCP server instance automatically: +1. Checks for local daemon socket (`.beads/bd.sock`) in your current workspace +2. Falls back to global daemon socket (`~/.beads/bd.sock`) +3. Routes requests to the correct database based on your current working directory +4. Auto-starts the daemon if it's not running (with exponential backoff on failures) +5. Auto-detects multiple repositories and prefers global daemon when 4+ repos are found + +**Why this is better than multiple MCP servers:** +- ✅ One config entry works for all your beads projects +- ✅ No risk of AI selecting wrong MCP server for workspace +- ✅ Better resource usage (one daemon instead of multiple) +- ✅ Automatic workspace detection without BEADS_WORKING_DIR + +**Note:** The daemon **auto-starts automatically** when you run any `bd` command (v0.9.11+). To disable auto-start, set `BEADS_AUTO_START_DAEMON=false`. + +**Alternative (legacy): Multiple MCP Server Instances** +If you must use separate MCP servers (not recommended): +```json +{ + "beads-webapp": { + "command": "beads-mcp", + "env": { + "BEADS_WORKING_DIR": "/Users/you/projects/webapp" + } + }, + "beads-api": { + "command": "beads-mcp", + "env": { + "BEADS_WORKING_DIR": "/Users/you/projects/api" + } + } +} +``` +⚠️ **Problem**: AI may select the wrong MCP server for your workspace, causing commands to operate on the wrong database. + +**Migration helper:** +```bash +# Migrate from local to global daemon +bd daemon --migrate-to-global + +# Or set environment variable for permanent preference +export BEADS_PREFER_GLOBAL_DAEMON=1 +``` + +### CLI Quick Reference + +If you're not using the MCP server, here are the CLI commands: + +```bash +# Find ready work (no blockers) +bd ready --json + +# Create new issue +bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json + +# Create with explicit ID (for parallel workers) +bd create "Issue title" --id worker1-100 -p 1 --json + +# Create with labels +bd create "Issue title" -t bug -p 1 -l bug,critical --json + +# Create multiple issues from markdown file +bd create -f feature-plan.md --json + +# Update issue status +bd update --status in_progress --json + +# Link discovered work (old way) +bd dep add --type discovered-from + +# Create and link in one command (new way) +bd create "Issue title" -t bug -p 1 --deps discovered-from: --json + +# Label management +bd label add