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..ef8b038 --- /dev/null +++ b/.beads/issues.jsonl @@ -0,0 +1,103 @@ +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:52.86662767Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.973078365Z","labels":["area/testing","priority/p3"]} +{"id":"meshmind-100","title":"Confirm REST/Celery shim retirement scope and provide source material for documentation","description":"Need authoritative summary of what changed before writing migration notes.","status":"open","priority":1,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:49:11.55221962Z","updated_at":"2025-10-20T08:49:11.55221962Z","labels":["area/docs","priority/p1"]} +{"id":"meshmind-101","title":"Restore outbound PyPI access or mirror so dependency lockfiles can be regenerated","description":"uv.lock updates are blocked until network/package mirrors are reachable.","status":"open","priority":1,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:49:56.81097747Z","updated_at":"2025-10-20T08:49:56.81097747Z","labels":["area/infrastructure","priority/p1"]} +{"id":"meshmind-102","title":"Track upstream pydantic packaging for target Python support","description":"We need confirmation that official wheels support our Python target before dropping compatibility shim.","status":"open","priority":2,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:50:02.297946734Z","updated_at":"2025-10-20T08:50:02.297946734Z","labels":["area/release","priority/p2"]} +{"id":"meshmind-103","title":"Complete API hardening backlog (llm_client rollout + override plumbing)","description":"Aggregate follow-up work discovered during backlog review; ensures UI exploration waits for stable APIs.","status":"open","priority":1,"issue_type":"task","assignee":"codex","created_at":"2025-10-20T08:50:24.249831658Z","updated_at":"2025-10-20T08:50:24.249831658Z","labels":["area/backend","priority/p1"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.081014834Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.212885499Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.3240942Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.447013892Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.567014858Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.665278957Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.775621101Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:54.962723409Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.080708753Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:52.986384256Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.191979732Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.303866736Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.4081723Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.525258417Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.702355473Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.856472417Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:55.970588738Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.080597902Z","labels":["area/performance","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.206582302Z","labels":["area/product","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.370709121Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.095455761Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.487904652Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.592796107Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.697182628Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.803109538Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:56.981883325Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.088396465Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.192315028Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.306852019Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.42471403Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.533663506Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.215623612Z","labels":["area/product","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.640606896Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.770871964Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.885122926Z","labels":["area/testing","priority/p3"],"dependencies":[{"issue_id":"meshmind-42","depends_on_id":"meshmind-41","type":"blocks","created_at":"2025-10-20T08:49:54.07331346Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:57.987666047Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.098351599Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.218692895Z","labels":["area/backend","priority/p3","status/blocked"],"dependencies":[{"issue_id":"meshmind-45","depends_on_id":"meshmind-101","type":"blocks","created_at":"2025-10-20T08:49:58.771197965Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.341665963Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.459055014Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.569068605Z","labels":["area/planning","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.787171648Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.329385935Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:58.895955398Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.001128453Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.112282213Z","labels":["area/tooling","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.430645702Z","labels":["area/research","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.546513033Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.654020719Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.764627482Z","labels":["area/data","priority/p3","status/blocked"],"dependencies":[{"issue_id":"meshmind-56","depends_on_id":"meshmind-99","type":"blocks","created_at":"2025-10-20T08:51:56.572110339Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:59.906013533Z","labels":["area/performance","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.01880631Z","labels":["area/backend","priority/p3","status/blocked"],"dependencies":[{"issue_id":"meshmind-58","depends_on_id":"meshmind-102","type":"blocks","created_at":"2025-10-20T08:50:04.324805541Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.132307598Z","labels":["area/infrastructure","priority/p3","status/blocked"],"dependencies":[{"issue_id":"meshmind-59","depends_on_id":"meshmind-96","type":"blocks","created_at":"2025-10-20T08:50:06.682589646Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.499686605Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.283747749Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.399034131Z","labels":["area/docs","priority/p3","status/blocked"],"dependencies":[{"issue_id":"meshmind-61","depends_on_id":"meshmind-98","type":"blocks","created_at":"2025-10-20T08:51:58.960042089Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.520798324Z","labels":["area/observability","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.626012554Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.723666057Z","labels":["area/docs","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.834534084Z","labels":["area/docs","priority/p3"],"dependencies":[{"issue_id":"meshmind-65","depends_on_id":"meshmind-62","type":"blocks","created_at":"2025-10-20T08:52:02.357404422Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:00.981696875Z","labels":["area/tooling","priority/p3","status/blocked"],"dependencies":[{"issue_id":"meshmind-66","depends_on_id":"meshmind-101","type":"blocks","created_at":"2025-10-20T08:51:53.559588602Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.113267585Z","labels":["area/testing","priority/p3"],"dependencies":[{"issue_id":"meshmind-67","depends_on_id":"meshmind-63","type":"blocks","created_at":"2025-10-20T08:52:04.657874055Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.227818676Z","labels":["area/testing","priority/p3"],"dependencies":[{"issue_id":"meshmind-68","depends_on_id":"meshmind-63","type":"blocks","created_at":"2025-10-20T08:52:06.883208889Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.331840038Z","labels":["area/docs","priority/p3"],"dependencies":[{"issue_id":"meshmind-69","depends_on_id":"meshmind-67","type":"blocks","created_at":"2025-10-20T08:52:10.831624507Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.624207493Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.434951664Z","labels":["area/tooling","priority/p3"],"dependencies":[{"issue_id":"meshmind-70","depends_on_id":"meshmind-63","type":"blocks","created_at":"2025-10-20T08:52:13.036267465Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.541889547Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.649505792Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.830918043Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:01.949062705Z","labels":["area/docs","priority/p3"],"dependencies":[{"issue_id":"meshmind-74","depends_on_id":"meshmind-73","type":"blocks","created_at":"2025-10-20T08:52:17.082587386Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.066044567Z","labels":["area/testing","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.163871672Z","labels":["area/docs","priority/p3"],"dependencies":[{"issue_id":"meshmind-76","depends_on_id":"meshmind-32","type":"blocks","created_at":"2025-10-20T08:52:19.812352597Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.294602405Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.400093311Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.521125043Z","labels":["area/infrastructure","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.735819853Z","labels":["area/backend","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.671725264Z","labels":["area/performance","priority/p3"]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:11:02.794824822Z","labels":["area/docs","priority/p3"]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.230687242Z","labels":["area/backend","priority/p0"]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.273184279Z","labels":["area/docs","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-83","depends_on_id":"meshmind-99","type":"blocks","created_at":"2025-10-20T08:48:56.969218886Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.310316867Z","labels":["area/docs","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-84","depends_on_id":"meshmind-98","type":"blocks","created_at":"2025-10-20T08:48:50.501922199Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.347010035Z","labels":["area/infrastructure","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-85","depends_on_id":"meshmind-95","type":"blocks","created_at":"2025-10-20T08:48:21.195126434Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.404126439Z","labels":["area/infrastructure","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-86","depends_on_id":"meshmind-96","type":"blocks","created_at":"2025-10-20T08:48:23.29731634Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.442711372Z","labels":["area/infrastructure","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-87","depends_on_id":"meshmind-96","type":"blocks","created_at":"2025-10-20T08:48:27.409198896Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.479156901Z","labels":["area/infrastructure","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-88","depends_on_id":"meshmind-97","type":"blocks","created_at":"2025-10-20T08:48:31.39927338Z","created_by":"daemon"},{"issue_id":"meshmind-88","depends_on_id":"meshmind-63","type":"blocks","created_at":"2025-10-20T08:48:34.125958329Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.51259508Z","labels":["area/infrastructure","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-89","depends_on_id":"meshmind-85","type":"blocks","created_at":"2025-10-20T08:48:36.414078817Z","created_by":"daemon"}]} +{"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:45:07.934359004Z","updated_at":"2025-10-20T08:45:07.934359004Z","closed_at":"2025-10-20T08:10:53.866210561Z","labels":["area/testing","priority/p3"]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.547614661Z","labels":["area/docs","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-90","depends_on_id":"meshmind-83","type":"blocks","created_at":"2025-10-20T08:48:59.232019636Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.582973795Z","labels":["area/infrastructure","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-91","depends_on_id":"meshmind-100","type":"blocks","created_at":"2025-10-20T08:49:13.530055067Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.615829617Z","labels":["area/docs","priority/p0","status/blocked"],"dependencies":[{"issue_id":"meshmind-92","depends_on_id":"meshmind-87","type":"blocks","created_at":"2025-10-20T08:49:22.222633918Z","created_by":"daemon"}]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.654712196Z","labels":["area/observability","priority/p2"]} +{"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","assignee":"codex","created_at":"2025-10-20T08:45:07.934359004Z","updated_at":"2025-10-20T08:52:52.689555668Z","labels":["area/product","priority/p2","status/blocked"],"dependencies":[{"issue_id":"meshmind-94","depends_on_id":"meshmind-35","type":"blocks","created_at":"2025-10-20T08:50:12.131928527Z","created_by":"daemon"},{"issue_id":"meshmind-94","depends_on_id":"meshmind-36","type":"blocks","created_at":"2025-10-20T08:50:14.068952371Z","created_by":"daemon"},{"issue_id":"meshmind-94","depends_on_id":"meshmind-103","type":"blocks","created_at":"2025-10-20T08:50:26.233189708Z","created_by":"daemon"}]} +{"id":"meshmind-95","title":"Provision a Celery worker + Redis staging stack reachable from integration and maintenance tests","description":"Required so bd ready tasks around maintenance retries and CI automation have real infrastructure to exercise.","status":"open","priority":0,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:48:13.994515726Z","updated_at":"2025-10-20T08:48:13.994515726Z","labels":["area/infrastructure","priority/p0"]} +{"id":"meshmind-96","title":"Deploy an authenticated staging REST/gRPC environment accessible for doc validation and grpcurl smoke tests","description":"Needed to unblock documentation verification tasks that require real endpoints.","status":"open","priority":0,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:48:16.350823987Z","updated_at":"2025-10-20T08:48:16.350823987Z","labels":["area/infrastructure","priority/p0"]} +{"id":"meshmind-97","title":"Stand up a release pipeline for protobuf client artifacts (build, sign, publish)","description":"Prerequisite for distributing generated clients externally once services stabilize.","status":"open","priority":1,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:48:19.045694894Z","updated_at":"2025-10-20T08:48:19.045694894Z","labels":["area/infrastructure","priority/p1"]} +{"id":"meshmind-98","title":"Provision long-lived Memgraph/Neo4j staging clusters dedicated to benchmarking","description":"Required for pagination and consolidation benchmarks that need stable external services.","status":"open","priority":0,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:48:46.939062717Z","updated_at":"2025-10-20T08:48:46.939062717Z","labels":["area/infrastructure","priority/p0"]} +{"id":"meshmind-99","title":"Regenerate a ≥10k-memory synthetic dataset and check it into shared storage for benchmarks","description":"Benchmark tasks need a reproducible dataset drop before we can record retry guidance.","status":"open","priority":0,"issue_type":"task","assignee":"human","created_at":"2025-10-20T08:48:54.774609913Z","updated_at":"2025-10-20T08:48:54.774609913Z","labels":["area/data","priority/p0"]} diff --git a/AGENTS.md b/AGENTS.md index 09ebc4c..dd6e650 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,20 +1,101 @@ # Agent Instructions -## 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. -- 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. -- 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. -- 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. - -## 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. +## Beads Issue Tracking +- Use the `bd` Beads CLI for all issue, task, and dependency tracking in this repository. +- Keep every issue up to date: assign `codex` when the work is agent-owned, `human` when it requires external help, and maintain `area/*`, `priority/*`, and `status/blocked` labels so filtering remains useful. +- Immediately capture newly discovered work or blockers in Beads before continuing implementation, and wire dependencies (`bd dep add`) so `bd ready` only lists actionable tasks. +- If the `.beads/` database is missing, run `bd init` (and `bd import -i .beads/issues.jsonl` if needed) and commit the resulting files. + +## Iteration Workflow +- Begin each session with `bd ready`/`bd list --status open` to understand available work and outstanding blockers. +- Close or update issues as soon as changes land, and keep dependency graphs accurate so downstream tasks stay blocked until prerequisites resolve. +- Add an entry to `CHANGELOG.md` for every change set with an ISO 8601 timestamp in America/New_York summarizing developer-facing impact and rationale. +- Rely on Beads for planning instead of sprawling Markdown checklists; use docs only for long-lived guidance that end users need. + +## Documentation & Communication +- Update `README.md`, `docs/`, and provisioning guides only when the implementation meaningfully changes behaviour or workflows touched by the turn. +- Keep high-level orientation docs (`ISSUES.md`, `PLAN.md`, `ROADMAP.md`, `RECOMMENDATIONS.md`) short and reference the relevant Beads issue IDs instead of duplicating task lists. +- Maintain `RESUME_NOTES.md` at the end of each turn so the next session starts with accurate context. + +## 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..37bf425 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,20 @@ # Changelog +## [2025-10-20T04:55:28-04:00 (America/New_York)] +### Changed +- Created staging and dataset blocker issues (`meshmind-95`–`meshmind-103`) and wired dependencies so `bd ready` surfaces only actionable work. +- Assigned `codex`/`human` ownership and `area/*` + `status/blocked` labels across the Beads database to enable filtering. +- Streamlined AGENTS.md and ISSUES.md to point back to the tracker while highlighting the new blocker queue. + +## [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..6508e6d 100644 --- a/ISSUES.md +++ b/ISSUES.md @@ -1,41 +1,34 @@ # Issues Checklist +> [!NOTE] +> Issue and task tracking lives in the Beads tracker (`bd`). Use this page as a quick orientation for the highest-impact items and check `bd show ` for full details. + ## 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. -- [x] Update OpenAI integration to match the current SDK (Responses API payload, embeddings API response structure). -- [x] Replace eager `tiktoken` imports in `meshmind.core.utils` and `meshmind.pipeline.compress` with guarded, optional imports. -- [x] Align declared Python requirement with supported dependencies (project now pins Python >=3.11,<3.13). +- [ ] `meshmind-95` – Provision a Celery worker + Redis staging stack so maintenance and integration tests can hit real services. +- [ ] `meshmind-96` – Deploy an authenticated REST/gRPC staging environment to validate curl/grpcurl documentation. +- [ ] `meshmind-98` – Stand up long-lived Memgraph/Neo4j clusters dedicated to benchmarking. +- [ ] `meshmind-99` – Regenerate and publish a ≥10k-memory synthetic dataset for consolidation benchmarks. +- [ ] `meshmind-101` – Restore outbound PyPI (or provide a mirror) so dependency locks can be regenerated. -- [ ] Maintain pip/uv package download access (confirmed working on 2025-10-15) so dependency lock regeneration can proceed reliably across sessions. -## High Priority -- [x] Provide configuration documentation and examples for Memgraph, Redis, and OpenAI environment variables. -- [x] Add automated tests or smoke checks that run without external services (mock OpenAI, stub Memgraph driver). -- [x] Create real docker-compose services for Memgraph and Redis or remove the placeholder file. -- [x] Centralize LLM provider usage behind a configurable client wrapper to remove direct `openai` imports scattered through the codebase. -- [x] Surface LLM override fields via REST/gRPC payloads and integration tests so service clients can select providers/models like the CLI. -- [x] Document Neo4j driver requirements and verify connectivity against a live cluster (integration suite now hits the docker-compose Neo4j service). -- [ ] Exercise the new namespace/entity-label filtering against live Memgraph/Neo4j datasets to confirm Cypher predicates behave as expected. -- [x] Regenerate `uv.lock` to reflect the updated dependency set (`pymgclient`, `fastapi`, `uvicorn`, extras) so CI tooling stays in sync. -## Medium Priority -- [x] Persist results from consolidation and compression tasks back to the database (currently in-memory only). -- [x] Refine `Memory.importance` scoring to reflect actual ranking heuristics instead of a constant. -- [x] Add vector, regex, and exact-match search helpers to match stated feature set or update documentation to demote them. -- [x] Harden Celery tasks to initialize dependencies lazily and log failures when the driver is unavailable. -- [x] Validate consolidation heuristics on larger datasets to measure ranking accuracy and resource usage (synthetic fixtures and benchmark scripts cover scale; rerun with production datasets when available). -- [x] Document and implement a conflict-resolution/backoff strategy for consolidation when merged metadata conflicts (configurable via `MAINTENANCE_MAX_ATTEMPTS` and `MAINTENANCE_BASE_DELAY_SECONDS`). -- [x] Revisit the compatibility shim once production environments support Pydantic 2.x so the real models can be restored (shim removed; native Pydantic models now required). -- [x] Replace the gRPC dataclass shim with generated protobuf definitions; follow-up integration tests remain pending until a real gRPC server is provisioned. -- [x] Implement a production-ready gRPC server (leveraging the generated protobuf modules). Async helpers now live in `meshmind.api.grpc_server`; integration tests remain blocked on staging infrastructure. -- [ ] Add end-to-end gRPC integration tests (deploy server + grpcurl smoke) once staging infrastructure is provisioned. -- [ ] Push graph-backed retrieval into Memgraph/Neo4j search capabilities once available (current wrappers now filter/paginate server-side but still score vectors in Python). -- [ ] Reconcile tests that depend on `Memory.pre_init` and outdated OpenAI interfaces with the current implementation. -- [x] Expose `memory_counts` via a gRPC endpoint to keep service interfaces aligned. -- [x] Add linting, formatting, and type-checking tooling to improve code quality. +## High Priority (next once blockers clear) +- [ ] `meshmind-82` – Implement backend-native vector similarity queries for Memgraph/Neo4j. +- [ ] `meshmind-83` – Run `scripts/consolidation_benchmark.py` with the refreshed dataset and document retry defaults. +- [ ] `meshmind-84` – Execute pagination benchmarks against the staging clusters and update retrieval guidance. +- [ ] `meshmind-85` – Add Celery/Redis-backed integration tests for maintenance retry flags. +- [ ] `meshmind-86` – Re-run curl/grpcurl documentation steps against the deployed staging endpoints. +- [ ] `meshmind-87` – Expand gRPC ingestion/search integration coverage once infrastructure lands. +- [ ] `meshmind-88` – Publish protobuf client artifacts after the release pipeline exists. +- [ ] `meshmind-89` – Automate the live integration suite in CI once maintenance tests pass. +- [ ] `meshmind-90` – Document ingestion workflows for the synthetic dataset generator after benchmarking. +- [ ] `meshmind-91` – Capture release notes for retiring REST/Celery shims once migration source material is ready. +- [ ] `meshmind-92` – Write gRPC CLI usage examples after the smoke tests complete. +- [ ] `meshmind-93` – Identify observability exporters and outline integration steps. +- [ ] `meshmind-94` – Explore UI concepts after the API hardening backlog (`meshmind-103`) lands. +- [ ] `meshmind-97` – Stand up the protobuf artifact release pipeline. +- [ ] `meshmind-100` – Gather authoritative REST/Celery retirement context for documentation. +- [ ] `meshmind-102` – Track upstream Pydantic packaging so the compatibility shim can be retired for good. +- [ ] `meshmind-103` – Finish the API hardening backlog to unblock downstream UX work. -- [ ] Validate the new Docker Compose stacks (root and `meshmind/tests/docker/`) on an environment with container support and document host requirements (ports, resources). -## Low Priority / Nice to Have -- [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. +## Reference +- Historical items completed prior to the Beads migration remain closed in the tracker (`bd list --status closed`). +- Use `bd ready` for the actionable queue after the blockers above are addressed. diff --git a/RESUME_NOTES.md b/RESUME_NOTES.md index 6d3726f..f9071f7 100644 --- a/RESUME_NOTES.md +++ b/RESUME_NOTES.md @@ -1,30 +1,17 @@ # Resume Notes -## Current Context - -- Branch: `work` (rebased from `integration`; PR target remains `integration`). -- Optional dependencies ship with the `.[dev,docs,testing]` extras; `uv sync --all-extras` (now pinned to Python 3.12 via `.python-version`) installs FastAPI/Uvicorn, Celery/Redis, Neo4j/Memgraph drivers, LLM tooling, and developer linters. The provisioning scripts in `run/` validate these extras before syncing `uv.lock`. -- Docker orchestration (root `docker-compose.yml` and `meshmind/tests/docker/*.yml`) provisions Memgraph, Neo4j, Redis, the Celery worker, and a gRPC server container; `pytest -m integration` exercises these services once the stack is running. -- Docker orchestration (root `docker-compose.yml` and `meshmind/tests/docker/*.yml`) now provisions Memgraph, Neo4j, Redis, the Celery worker, and a gRPC server container driven by the new CLI command. -- The documentation guard enforces updates whenever code within mapped directories changes; planning artifacts (`PLAN.md`, `PROJECT.md`, `SOT.md`, `ROADMAP.md`, `PLANNING_THOUGHTS.md`, `research/`) remain synchronized per agent instructions. - ## Latest Changes - -- Added live integration coverage (`meshmind/tests/test_integration_live.py`) for Memgraph, Neo4j, and Redis, introduced a pytest marker configuration, and documented the workflow across README/SETUP/docs. -- Generated a fresh `uv.lock`, pinned `.python-version` to 3.12, and updated install docs to standardise on `uv sync --all-extras`. -- Created `scripts/generate_synthetic_dataset.py` for large JSONL/CSV corpora and referenced it across benchmarking docs. -- Updated documentation and planning collateral (README.md, SETUP.md, docs/development.md, docs/testing.md, docs/operations.md, PROJECT.md, PLAN.md, RECOMMENDATIONS.md, ROADMAP.md, ENVIRONMENT_NEEDS.md, NEEDED_FOR_TESTING.md, SOT.md, PLANNING_THOUGHTS.md, DUMMIES.md, TODO.md, RESUME_NOTES.md) to reflect the integration workflow, dataset generation, and the new Pydantic policy. +- Reviewed the Beads backlog and created explicit blocker issues (`meshmind-95`–`meshmind-103`) so infrastructure/data gaps stop surfacing as ready work. +- Assigned codex/human ownership plus `area/*` and `status/blocked` labels across the tracker, giving `bd ready` a clean next-action queue. +- Streamlined AGENTS.md and ISSUES.md to reference Beads directly while highlighting the new blocker lineup. ## Environment State - -- Docker Compose is available; starting the stack locally (`docker compose up -d`) allows integration tests (`pytest -m integration`) to hit live Memgraph/Neo4j/Redis instances. -- Internet access is currently enabled and optional packages have been installed via `uv sync`. Keep the network open so dependency locks and maintenance scripts remain functional. -- Changelog entries must continue using Eastern time with timezone codes; remember to update `CHANGELOG.md` after every batch of changes. +- `bd ready` now surfaces 10 items: two agent-owned tasks (`meshmind-82`, `meshmind-103`, `meshmind-93`) and seven human-owned blockers (Celery/Redis stack, staging REST/gRPC env, benchmarking clusters, dataset regeneration, protobuf release pipeline, REST/Celery migration context, PyPI access). +- The repository keeps Beads metadata in `.beads/issues.jsonl`; run `bd export -o .beads/issues.jsonl` after mutating the database to sync labels into git. +- Continue recording changelog entries with America/New_York timestamps and maintain Beads dependencies whenever new blockers emerge. ## Next Session Starting Points - -1. Address remaining `TODO.md` priority items (backend-native vector similarity, Celery worker integration, grpcurl end-to-end tests) now that graph services are accessible locally. -2. Automate the integration suite in CI and capture resource requirements for shared infrastructure. -3. Prepare grpcurl-based smoke tests for `meshmind serve-grpc` and plan protobuf client packaging once integration coverage extends beyond the Python stub. -4. Feed findings from large synthetic datasets into retry/backoff defaults and document recommended values in `ENVIRONMENT_NEEDS.md`. -5. Continue tracking shim retirements in `DUMMIES.md` and follow the cleanup plan in `CLEANUP.md` so remaining fakes can be removed when infrastructure allows. +1. Once the human-owned blockers resolve, tackle `meshmind-82` to push vector similarity scoring into the backend. +2. Follow up with benchmarking/doc tasks (`meshmind-83`/`meshmind-84`/`meshmind-90`) after the dataset and clusters exist. +3. Expand gRPC coverage (`meshmind-85`–`meshmind-88`) as soon as the Celery/Redis stack and staging endpoints are available. +4. Keep monitoring `meshmind-101` (PyPI access) so dependency lock updates and gRPC tooling installs can proceed in future iterations. 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