[BUG] sync_changes crashes in local Docker + Postgres + streamable-http MCP with IndexError: pop from an empty deque

[bengreeno]

Bug Description

In a local Docker deployment using Postgres (not SQLite), Basic Memory works for MCP requests and agent-driven edits, but local filesystem watcher/sync does not work reliably.

Manual markdown edits on disk are not picked up automatically, and enabling sync_changes causes crashes. I currently have to keep sync_changes: false to keep the setup usable.

Steps To Reproduce

1. Run Basic Memory 0.21.5 locally in Docker with a Postgres backend (postgresql+asyncpg), with the project mounted at /app/data/main.
2. Start MCP with:
   basic-memory mcp --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp
3. Enable sync_changes in config.
4. Make manual edits to markdown files in the mounted project directory.
5. Observe watcher instability / crashes instead of reliable sync.

Expected Behavior

Manual markdown edits on disk should be detected and synced automatically when sync_changes is enabled in a local Postgres-backed deployment.

Actual Behavior

What works:

• MCP initializes and serves requests
• bm project info main --json works
• agent-driven edits work

What does not work:

• manual edits to markdown files on disk are not picked up automatically
• enabling sync_changes causes crashes
• I had to keep sync_changes: false to keep the setup stable

Crash signature I saw:

IndexError: pop from an empty deque

Trace lands in:

/app/.venv/lib/python3.13/site-packages/anyio/_backends/_asyncio.py
/python/cpython-3.13.13-linux-x86_64-gnu/lib/python3.13/asyncio/base_events.py:_run_once

I also saw:

ASGI callable returned without completing response.

Relevant log snippet:

ERROR:    ASGI callable returned without completing response.

File "/app/.venv/lib/python3.13/site-packages/anyio/_backends/_asyncio.py", line 2358, in run
    self._run_once()
File "/python/cpython-3.13.13-linux-x86_64-gnu/lib/python3.13/asyncio/base_events.py", line 2046, in _run_once
IndexError: pop from an empty deque

There were also repeated shutdown/restart sequences around the crash:

INFO:     Shutting down
INFO:     Waiting for application shutdown.
INFO:     Application shutdown complete.
INFO:     Finished server process [1]

Environment

• OS: Ubuntu 24.04.4 LTS
• Python version: 3.13.13
• Basic Memory version: 0.21.5
• Installation method: Docker (ghcr.io/basicmachines-co/basic-memory:latest)
• Claude Desktop version (if applicable): N/A

Additional Context

MCP command:

basic-memory mcp --transport streamable-http --host 0.0.0.0 --port 8000 --path /mcp

Docker setup:

• basic-memory container runs MCP over streamable-http
• basic-memory-db is a separate postgres:16-alpine container
• ./data is mounted to /app/data
• ./config is mounted to /home/appuser/.basic-memory

Current config that stays mostly stable:

{
  "database_backend": "postgres",
  "sync_changes": false,
  "skip_initialization_sync": true,
  "sync_delay": 1000
}

One thing I noticed: bm project info main --json shows a SQLite-style system.database_path like:

"database_path": "/home/appuser/.basic-memory/memory.db",
"database_size": "0.00 MB"

even though this deployment is definitely using Postgres. That may just be a reporting issue, but I wanted to mention it.

Possible Solution

I don’t have a real fix yet, but my guess is this may be in the watcher / MCP server lifecycle / async shutdown path for the local Docker + Postgres + streamable-http combination, rather than in the core MCP request path itself.

The SQLite-looking database_path in bm project info may be unrelated and just a misleading status/reporting field.

[bengreeno]

I can also test a fresh local Docker + Postgres setup with both startup sync and watcher sync enabled, starting from an empty project and then gradually adding notes. That should help tell us whether this is runtime/lifecycle related or something about my existing corpus/state. Happy to try that if it would be useful.

[bengreeno]

I looked a bit more closely at the Docker examples in the image/repo. The default local Docker compose seems to assume sync is on, and there’s a separate Postgres compose helper that uses pgvector/pgvector:pg17. My setup is a bit different from those examples: local Docker, streamable-http MCP, Postgres backend, but with postgres:16-alpine and semantic search disabled. Not sure if that difference matters for the watcher/sync issue, but I wanted to mention it.

[bengreeno]

I ran a fresh clean-room test to rule out existing corpus / DB state.

I stood up a brand-new isolated Docker stack with:

• Basic Memory 0.21.5
• MCP over streamable-http
• Postgres on pgvector/pgvector:pg17
• sync_changes=true
• skip_initialization_sync=false
• semantic_search_enabled=true
• completely empty data/main project

Result:

• Postgres came up healthy
• Basic Memory started, completed app startup once, then hit the same crash
• it entered a restart loop

Same failure signature:

IndexError: pop from an empty deque

Trace still lands in:

• anyio/_backends/_asyncio.py
• asyncio/base_events.py:_run_once

So this does not appear to depend on my existing notes, old DB state, or the older plain Postgres image I was using before. It reproduces on a fresh empty stack as well.

[bengreeno]

I ran the SQLite comparison too, and it narrows things down further.

Fresh SQLite test:

• local Docker
• streamable-http
• empty data/main
• sync_changes=true
• skip_initialization_sync=false

Result:

• container started cleanly
• no restart loop
• no IndexError: pop from an empty deque

I also verified actual watcher behavior on SQLite:

• manually copied a markdown file into the empty project
• Basic Memory picked it up automatically
• then manually edited the same file
• Basic Memory picked up the modification automatically too

bm project info main --json showed watch_status.running=true, error_count=0, and successful new / modified events for the file.

So at this point the behavior seems to be:

• fresh Postgres + watcher enabled -> crashes
• fresh SQLite + watcher enabled -> works

That makes this look much more like a Postgres-backed watcher/sync path issue than a general file-watching issue.