Cloud sync fails: session mutations missing directory field when MCP server upserts sessions

[quirozino]

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

[BaltasarOrtiz]

I ran into the same bug. After investigating, I traced it to mcp.go — every call site that uses defaultSessionID() creates the session with a hardcoded empty string:

s.CreateSession(sessionID, project, "")  // directory always ""

The sessions table does get the correct directory later via the Claude Code session-start.sh hook (which calls POST /sessions with the real path), but by then the mutation payload is already written — and the cloud canonicalizer validates the payload, not the current session state. So the hook fixing the sessions record doesn't help sync.

One thing I noticed that isn't mentioned here: sub-agents make this significantly worse. When using orchestrated sub-agents (e.g. via Claude Code's Agent tool), each sub-agent calls mem_save or mem_session_summary without an explicit session_id, independently triggering the implicit session creation — all with directory: "". A normal single-user session might produce 1–2 bad mutations; a multi-agent orchestrated flow produced 18+ bad mutations in a single run in my case.

For the fix, replacing the hardcoded "" with os.Getwd() in all handlers that call CreateSession with an implicit ID seems like the right call — it's already consistent with how resolveWriteProject() handles project detection.

[Alan-TheGentleman]

This are the needed steps

https://github.com/Gentleman-Programming/engram/blob/main/docs/engram-cloud/quickstart.md#existing-project-upgrade-path-recommended

[aleksandarperak33-hub]

The issue is that mem_save in the MCP server isn't passing the directory field when creating session mutations.

If the MCP server has access to the directory info, add it to the mutation payload in the session upsert logic:

const mutation = {
  id: session.id,
  project: session.project,
  started_at: session.started_at,
  directory: session.directory || ''
};

If the canonicalizer should handle missing data, query the sessions table as a fallback:

if entity == 'session' and 'directory' not in payload:
    session = db.query("SELECT directory FROM sessions WHERE id = ?", payload['id']).first()
    payload['directory'] = session.directory if session else ''

The first approach fixes the root cause. The second is a defensive fallback that won't block syncs while tracking down where directory gets lost in the MCP flow.

[Alan-TheGentleman]

Ohh gotcha, that's because the MCP now infers the directory noy the agent. I'll fix the bug Alan Buscaglia *GDE & MVP | Founder, Gentleman Programming | AI Adoption Consultant* ***@***.*** [image: LinkedIn] <https://www.linkedin.com/in/alanbuscaglia/> [image: X] <https://twitter.com/G_Programming> [image: Youtube] <https://www.youtube.com/c/GentlemanProgramming> [image: Instagram] <https://www.instagram.com/gentlemanprogramming/> [image: Tiktok] ***@***.***>

…

On Mon, Apr 27, 2026, 07:14 aleksandarperak33-hub ***@***.***> wrote: *aleksandarperak33-hub* left a comment (Gentleman-Programming/engram#249) <#249 (comment)> The issue is that mem_save in the MCP server isn't passing the directory field when creating session mutations. If the MCP server has access to the directory info, add it to the mutation payload in the session upsert logic: const mutation = { id: session.id, project: session.project, started_at: session.started_at, directory: session.directory || ''}; If the canonicalizer should handle missing data, query the sessions table as a fallback: if entity == 'session' and 'directory' not in payload: session = db.query("SELECT directory FROM sessions WHERE id = ?", payload['id']).first() payload['directory'] = session.directory if session else '' The first approach fixes the root cause. The second is a defensive fallback that won't block syncs while tracking down where directory gets lost in the MCP flow. — Reply to this email directly, view it on GitHub <#249 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABU5FSFHT6O7YDDY3U4ISZL4X3UFHAVCNFSM6AAAAACYHBEKXWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGMRUGM2DMMJTGU> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/ABU5FSBOGLYI6QNWROE5PE34X3UFHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZSGQZTINRRGM22M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/ABU5FSCCKSVIHVTX7ZNB53D4X3UFHA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMZSGQZTINRRGM22M4TFMFZW63VHMNXW23LFNZ2KKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you commented.Message ID: ***@***.***>

[Alan-TheGentleman]

Fixed on main in 39d48e9. The MCP server now creates implicit/default sessions with the process current working directory, so new session upsert sync mutations include a valid directory instead of triggering cloud canonicalization failures. CI is green for that commit. Closing.