Skip to content

fix: tolerate missing directory in session upsert mutations for cloud sync#250

Open
quirozino wants to merge 1 commit intoGentleman-Programming:mainfrom
quirozino:fix/session-directory-required-cloud-sync
Open

fix: tolerate missing directory in session upsert mutations for cloud sync#250
quirozino wants to merge 1 commit intoGentleman-Programming:mainfrom
quirozino:fix/session-directory-required-cloud-sync

Conversation

@quirozino
Copy link
Copy Markdown

Bug Description

When using the MCP server with ENGRAM_CLOUD_AUTOSYNC=1, cloud sync fails with:

engram: canonicalize cloud chunk: mutations[N]: session payload directory is required for upsert

Root Cause

The MCP server generates sync_mutations entries for session upserts that are missing the directory field in the JSON payload. Example of a problematic mutation payload:

{"id":"manual-save-ddata","project":"ddata","started_at":"2026-04-18 00:41:04"}

The directory field is absent entirely (not empty string, but missing). The cloud chunk canonicalizer requires this field for session upserts and fails hard with no fallback.

Repro Steps

  1. Configure engram MCP with ENGRAM_CLOUD_AUTOSYNC=1 and a cloud endpoint
  2. Use mem_save tool from the MCP multiple times in a session
  3. Run engram sync --cloud --project <name>
  4. Observe: mutations[N]: session payload directory is required for upsert

Workaround

Manually patch the affected rows before syncing:

UPDATE sync_mutations 
SET payload = json_set(payload, '$.directory', '/path/to/project')
WHERE entity = 'session' 
AND json_extract(payload, '$.directory') IS NULL;

Expected Behavior

Either:

  • The MCP server should always include directory in session mutation payloads
  • OR the cloud sync canonicalizer should be tolerant of missing directory and use a fallback from the sessions table

Environment

  • engram client: v1.14.0 (Windows, scoop)
  • engram server: v1.14.1 (Docker, self-hosted)
  • OS: Windows 11 / PowerShell
  • MCP tools profile: --tools=agent

… sync

When the MCP server generates session upsert mutations (e.g. for
manual-save sessions), it may omit the directory field. The cloud
sync canonicalizer was failing hard with an error instead of using
a safe fallback.

Replace the hard error with a fallback to '.' so cloud sync is not
blocked by sessions created without a working directory.

Fixes Gentleman-Programming#249
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant