# Reported issues for io.github.Abhigyan-Shekhar/Waggle-mcp

Pod holds 22 of 45 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [io.github.Abhigyan-Shekhar/Waggle-mcp](/mcp/io-github-abhigyan-shekhar-waggle-mcp).

## Most discussed

### [feature] Add memory export preview before saving to JSON/Markdown

### Problem or use case

Currently, users can export stored memory, but there is no preview of the content before the export is written to disk. A preview would help users verify the data and avoid exporting unnecessary or sensitive information.

**Problem**

- Users cannot inspect exported content beforehand.
- Accidental export of unwanted memory entries is possible.
- Large exports are difficult to verify after the file has already been generated.

### Proposed solution

- Add a --preview fla

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/572) · 2026-07-18 · closed · external user · 4 comments

### Add memory usage statistics to the waggle-mcp doctor command

### Problem or use case

The `waggle-mcp doctor` command verifies the installation and configuration of Waggle, but it does not provide any information about the current memory database.

Users cannot quickly check how much memory has been stored, how many nodes or edges exist, or which backend and embedding model are currently being used. This makes it harder to verify that Waggle is actively storing and retrieving memory.

### Proposed solution

Extend the `waggle-mcp doctor` command to includ

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/557) · 2026-07-11 · open · external user · 4 comments

### [Feature Request]: Add a doctor --json mode for structured diagnostics

### Problem or use case

Currently, the `waggle-mcp doctor` command is incredibly useful for human users to troubleshoot their configuration and setup. However, the output is formatted as plain text, making it difficult for automation scripts, issue templates, or other tooling to parse the diagnostic results reliably.

### Proposed solution

Add a `--json` flag to the `waggle-mcp doctor` command. When this flag is passed, the tool should output the diagnostic results as a structured, machine-rea

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/372) · 2026-06-12 · closed · outside contributor · 4 comments

### [bug] : Malformed numeric environment variables bypass configuration validation and crash startup

### Summary

Malformed numeric environment variables cause startup failure during configuration loading. `AppConfig.from_env()` performs direct `int()` and `float()` conversions on environment variables before configuration validation is executed.

As a result, invalid values such as:

```powershell
$env:WAGGLE_RATE_LIMIT_RPM="abc"
```

or

```powershell
$env:WAGGLE_HYBRID_VECTOR_WEIGHT="abc"
```

cause raw Python `ValueError` exceptions during startup instead of being surfaced through Waggle's 

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/293) · 2026-06-08 · closed · outside contributor · 4 comments

### bug(networking): socket_recv assumes recv(4) returns the full TCP length header

### Summary

### Summary

`socket_recv()` assumes that a single `recv(4)` call will always return the complete 4-byte TCP length header. TCP does not guarantee this behavior, and fragmented reads can cause `struct.unpack()` to fail when fewer than 4 bytes are returned.

### Steps to reproduce

### Steps to reproduce

1. Open `src/rlm/core/comms_utils.py`
2. Locate `socket_recv()`
3. Observe that the length header is read using:

```python
raw_len = sock.recv(4)
length = struct.unpack(">I", raw_

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/269) · 2026-06-06 · open · external user · 5 comments

### perf(graph): dedup_candidates is quadratic over all candidate pairs

File: src/waggle/graph.py:6979-7025

dedup_candidates() builds every compatible node pair in a nested loop and computes cosine similarity for each pair. That is O(N^2) over the filtered node set, so the cost grows rapidly as tenant history grows.

Impact: the duplicate-review endpoint becomes CPU-bound on large tenants and can dominate request latency long before the graph is truly massive. A surgical fix would need an index or approximate candidate pruning step before pairwise comparison.

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/197) · 2026-06-01 · open · outside contributor · 4 comments

### docs: add requirements.txt so contributors can install dependencies easily

### Documentation gap

This project does not have a `requirements.txt` file. The README itself.
acknowledges this in saying:
No requirements.txt file provided; please install the 
core libraries by hand.”
This creates friction for new contributors and users that 
First time cloning the repo.
_

### Relevant page or file

_No response_

### Proposed improvement

Create a `requirements.txt` file in the root of the repo
with the following content:
discord.py>=2.0.0
python-dotenv>=1.0.0
And update t

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/184) · 2026-06-01 · closed · external user · 6 comments

### [bug]: graph_delete_edge uses graph:read instead of graph:write scope

### Summary

The `graph_delete_edge` endpoint currently authorizes requests using:

```python
_require_http_scope(request, "graph:read")
```

However, edge deletion is a graph mutation operation, and other graph mutation endpoints require `graph:write`.

This creates an authorization scope mismatch and may allow clients with read-only permissions to delete graph edges.

For consistency with other graph mutation endpoints, `graph_delete_edge` should require `graph:write` permissions.

### Steps 

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/46) · 2026-05-29 · closed · external user · 4 comments

## Most recent

### [bug] ImportError: cannot import name 'request_ctx' from mcp.server.lowlevel.server on fresh install (waggle-mcp 0.0.1, mcp 2.1.1)

### Summary

Running `waggle --help` immediately after a fresh pip install crashes with an ImportError. waggle/server.py imports `request_ctx` from 
`mcp.server.lowlevel.server`, but this name does not exist in mcp 2.1.1, the version currently resolved by pip when installing waggle-mcp. The CLI is completely unusable out of the box for new users.

### Steps to reproduce

1. pip install waggle-mcp
2. waggle --help
3. Observe ImportError instead of the expected help output

### Expected behavior

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/704) · 2026-08-28 · open · external user · 1 comment

### [Feature] Add a Scroll-to-Top button for improved navigation

### Problem or use case

Users reading long documentation pages or navigating through the website need to manually scroll back to the top after reaching the bottom. This can become inconvenient as more content is added and affects the overall browsing experience.

A built-in scroll-to-top button would provide quicker navigation and improve usability.

### Proposed solution

Add a floating "Scroll-to-Top" button that appears once the user scrolls beyond a certain distance.

### Expected behavior

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/563) · 2026-07-14 · closed · outside contributor · 2 comments

### [bug] Neo4j _next_transcript_turn_index ignores project/agent_id — turn-index collisions across scopes

## Summary
The Neo4j backend computes the next transcript `turn_index` from only `tenant_id` + `session_id`, while the SQLite backend also scopes by `project` and `agent_id`. When the same `session_id` is reused across different projects/agents within a tenant, Neo4j assigns colliding `turn_index` values, whereas SQLite keeps per-(session, project, agent) sequences.

## Evidence
- Neo4j: `src/waggle/neo4j_graph.py:3512` `_next_transcript_turn_index(self, session, *, session_id)` runs `MATCH (t:M

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/562) · 2026-07-11 · open · external user · 2 comments

### [bug] abhi namespaced import leaves context_window_edges dangling (window IDs not remapped)

## Summary
When importing a `.abhi` document with a non-empty `namespace`, node, edge, transcript, and context-window IDs are all remapped via `_namespace_id`/`node_id_map`, but `context_window_edges` are copied verbatim. Their `source_window_id`/`target_window_id` still reference the **original** (un-namespaced) window IDs, so every cross-window edge dangles after import.

## Evidence
- `src/waggle/abhi.py` import path remaps:
  - nodes: `node_id_map` (lines ~1771–1774)
  - edges: `source_id`/`

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/561) · 2026-07-11 · open · external user · 2 comments

### [bug] abhi merge: resolve_abhi_conflict always raises — conflict_records never persisted to merged manifest

## Summary
After a three-way `.abhi` merge produces conflicts, `resolve_abhi_conflict` cannot resolve any of them because the merged document's manifest never contains the `conflict_records` list. Every call raises `ConflictResolutionError("No conflict records found in merged document.")`, making post-merge interactive conflict resolution permanently unusable.

## Evidence
- `merge_abhi_documents` (`src/waggle/abhi.py:1262`) collects conflicts into a local `conflict_records` list (lines 1296, 13

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/560) · 2026-07-11 · open · external user · 2 comments

### [bug] Neo4j backend ignores temporal validity (valid_to) — returns expired/superseded nodes

## Summary
The SQLite backend enforces temporal validity by default (it drops nodes whose `valid_to` has passed, unless `include_invalidated=True`/`as_of` is given). The Neo4j backend never applies this filtering, so `query`, `aggregate`, `get_related`, and `tiered_query` return expired/superseded nodes that SQLite would hide — a silent correctness divergence between the two documented backends.

## Evidence
- SQLite applies validity filtering in `src/waggle/graph/base.py` (`_filter_valid_nodes`

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/559) · 2026-07-11 · open · external user · 2 comments

### [bug] Neo4j backend: query_graph/aggregate_graph/transcript listing crash with TypeError (missing expand_depth/include_invalidated/as_of/offset)

## Summary
When Waggle runs with `WAGGLE_BACKEND=neo4j`, the core retrieval tools `query_graph` / `aggregate_graph` and the `GET /transcripts` HTTP endpoint raise `TypeError` because the Neo4j backend methods do not accept keyword arguments that the server always passes and that the SQLite backend accepts.

## Evidence
- `src/waggle/neo4j_graph.py:1522` — `query()` signature is `(*, query, max_nodes, max_depth, agent_id, project, session_id, retrieval_mode)` and **lacks** `expand_depth`, `includ

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/558) · 2026-07-11 · open · external user · 2 comments

### Add a runnable Python usage example for observe_conversation and query_graph

Problem 

The examples/ directory currently contains only deployment and client-config files (e.g. MCP client setup, .mcpb bundles) — there's no standalone, runnable Python script showing the core memory workflow end-to-end. docs/ has 25+ conceptual markdown files, but none of them are executable walkthroughs.
New contributors and users adopting Waggle programmatically (outside an MCP client) have to piece together the workflow from the README's Session 1/2/3 narrative rather than running actual

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/544) · 2026-07-07 · closed · external user · 2 comments

### [Feature] Improve regression test coverage for code_extraction parser edge cases

### Problem or use case

## Problem

The `code_extraction` module currently covers common parsing scenarios, but several parser edge cases are not protected by dedicated regression tests.

Examples include:

- Empty fenced code blocks
- Empty input
- Unknown language fallback behavior
- Unknown language blocks without recognizable symbols

Although these behaviors currently work correctly, future parser refactoring could unintentionally change them without being detected by the existing test sui

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/537) · 2026-07-04 · open · outside contributor · 1 comment

### Improve test reliability by fixing skip handling, path resolution, and embedding normalization

### Summary

I found three related issues that affect the robustness and reliability of the test suite.

Issue 1: Incorrect use of assert with pytest.skip()
Issue 2: Path insertion may not reliably prevent duplicates - The setup code checks whether str(SRC) exists in sys.path before inserting it. Since sys.path entries may have different path representations (relative vs. absolute/resolved), duplicate entries can still be introduced. Using the resolved path provides a more reliable comparison.
I

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/514) · 2026-07-03 · closed · outside contributor · 2 comments

### [docs]  Document tenant_id isolation guarantees for multi-tenant deployments

### Documentation gap

The CONTRIBUTING.md Scoping/Tenancy table lists tenant_id as providing "Top-level multi-tenant isolation," but does not explain if this provides enforced data separation (row-level security) or merely logical namespace scoping.

### Relevant page or file

_No response_

### Proposed improvement

Add a dedicated "Multi-Tenant Isolation" section to the deployment docs explicitly stating that tenant_id provides logical namespace filtering (not enforced RLS) and recommending s

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/509) · 2026-07-01 · closed · outside contributor · 1 comment

### [docs]  Clarify that WAGGLE_MODEL=deterministic disables semantic retrieval

### Documentation gap

The README (line 375) describes WAGGLE_MODEL=deterministic as having "slightly lower retrieval quality". This significantly understates the impact. Deterministic mode replaces the sentence-transformer embedding model with SHA-256 hash bucketing, which completely disables semantic similarity. Users may unknowingly deploy this in production.

### Relevant page or file

README.md, CONTRIBUTING.md, docs/environment-variables.md

### Proposed improvement

 Replace "slightly low

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/508) · 2026-07-01 · closed · outside contributor · 1 comment

### [bug]  Random ablation subqueries produce duplicates causing redundant graph retrievals

### Summary

 In src/waggle/recursive_context.py (lines 227–247), when the random_subqueries ablation flag is set, the random slicer generates word slices from the query but doesn't track which substrings have already been generated. For short queries, all max_subqueries entries are identical. Each duplicate triggers a separate graph retrieval call, wasting compute.

### Steps to reproduce

Run a test script mimicking the random slicer loop with a short query .
Print the generated subqueries
Obs

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/507) · 2026-07-01 · closed · outside contributor · 1 comment

### [bug]  Memory leak in AsyncMemoryOrchestrator — _known_turn_ids grows unboundedly

### Summary

AsyncMemoryOrchestrator tracks processed conversation turns in self._known_turn_ids, which is an unbounded set[str] (src/waggle/orchestrator.py, line 185). Every call to on_assistant_turn() adds a SHA-256 hash to this set, but entries are never evicted. In a long-running MCP server processing thousands of turns, this causes continuous memory growth proportional to the number of turns processed, constituting a memory leak.

### Steps to reproduce

Run python reproduce_mem_leak.py
Obs

[Read the thread](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues/506) · 2026-07-01 · closed · outside contributor · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/Abhigyan-Shekhar/Waggle-mcp/issues).