Reject empty observation titles before persistence

[andrzejk87]

📋 Pre-flight Checks

• I have searched existing issues and this is not a duplicate.
• I understand this issue needs status:approved before a PR can be opened.

📝 Bug Description

Engram v1.16.1 allows first-party save paths to persist an observation with an empty or whitespace-only title.

This creates a local observation row with observations.title = '' and enqueues a cloud observation upsert mutation with sync_mutations.payload.title = ''.

Later, engram doctor / cloud sync correctly treats the same mutation as invalid because observation upserts require a non-empty title. The project then becomes blocked until the local database and frozen mutation payload are manually repaired.

This is a write-side validation / invariant gap:

• CLI engram save accepts title="".
• MCP mem_save accepts title="".
• store.AddObservation accepts Title="".
• cloud/doctor/chunk validators reject empty title for observation upserts.

Related but not duplicate:

• Cloud repair should backfill and report legacy mutation required fields #340 tracks legacy repair/backfill/reporting for malformed required fields.
• fix(mcp,pi): mem_session_summary persists observations with empty content, blocking cloud upgrade #393 fixed the same class of problem for empty content in mem_session_summary.
• mem_save via MCP saves empty observations — parameter mismatch #132 / MCP mem_save tool silently drops observation body — content column always empty #363 fixed older MCP content/body mismatch issues.

This issue is about current v1.16.1 allowing new malformed empty-title observation upserts.

🔄 Steps to Reproduce

Use an isolated data directory so the real database is not touched:

tmp="$(mktemp -d)"
export ENGRAM_DATA_DIR="$tmp/.engram"

engram save "" "Content for empty-title reproduction" \
  --type discovery \
  --project empty-title-test

engram doctor --json --project empty-title-test

Observed CLI output:

Memory saved: #1 "" (discovery)

Inspecting the isolated SQLite database shows:

SELECT id, quote(title), length(title), project
FROM observations;

-- id=1, title='', length(title)=0, project='empty-title-test'

And the queued cloud mutation contains:

{
  "sync_id": "obs-...",
  "session_id": "manual-save-empty-title-test",
  "type": "discovery",
  "title": "",
  "content": "Content for empty-title reproduction",
  "project": "empty-title-test",
  "scope": "project"
}

Doctor then reports a blocking malformed mutation:

sync_mutation_required_fields
sync_mutation_payload_missing_required_fields
observation payload missing required fields: title

The same behavior is reproducible through MCP mem_save:

{
  "name": "mem_save",
  "arguments": {
    "title": "",
    "content": "Content via MCP empty-title reproduction",
    "type": "discovery",
    "capture_prompt": false
  }
}

The tool returns success:

Memory saved: "" (discovery)

and persists observations.title = '' plus sync_mutations.payload.title = ''.

✅ Expected Behavior

Engram should reject empty or whitespace-only titles before persistence.

Expected behavior:

• CLI engram save "" "content" fails loudly.
• CLI engram save " " "content" fails loudly.
• MCP mem_save(title="", content="...") returns a tool error.
• MCP mem_save(title=" ", content="...") returns a tool error.
• store.AddObservation rejects empty/whitespace-only Title, so no caller can create an invalid observation or cloud mutation.

No observation row and no cloud mutation should be created for invalid titles.

❌ Actual Behavior

Engram accepts the write, creates a local observation, and queues a cloud mutation that later blocks doctor/cloud sync.

🧪 Verified On

engram 1.16.1
repo: Gentleman-Programming/engram
commit: 07445ba99eac95083d7c6d56c5d795bb68e90834
tag: v1.16.1

This was also reproduced by running from a clean upstream checkout with:

go run ./cmd/engram save "" "Content from clean source repro" \
  --type discovery \
  --project clean-source-empty-title

using an isolated ENGRAM_DATA_DIR=/tmp/....

The source checkout was clean and matched origin/main / v1.16.1.

🔍 Suspected Root Cause

internal/mcp/mcp.go validates content, but not title:

title, _ := req.GetArguments()["title"].(string)
content, _ := req.GetArguments()["content"].(string)

if strings.TrimSpace(content) == "" {
    ...
}

savedID, err := s.AddObservation(store.AddObservationParams{
    Title: title,
    ...
})

cmd/engram/main.go also forwards the CLI title unchanged:

title := os.Args[2]
content := os.Args[3]
...
Title: title,

internal/store/store.go strips private tags but does not enforce a non-empty title:

title := stripPrivateTags(p.Title)
content := stripPrivateTags(p.Content)

But cloud/chunk validation requires non-empty title:

body.Title = strings.TrimSpace(body.Title)
if body.Title == "" {
    return "", "", fmt.Errorf("observation payload title is required for upsert")
}

and cloud server validation also rejects it:

if strings.TrimSpace(observation.Title) == "" {
    return fmt.Errorf("observations[%d].title is required", i)
}

🛠 Suggested Fix

Enforce the same invariant on the write side:

1. MCP mem_save:

   • trim title
   • reject empty/whitespace-only title

2. CLI engram save:

   • trim title
   • reject empty/whitespace-only title

3. store.AddObservation:

   • enforce non-empty title after stripPrivateTags and trim
   • return an error before any row or sync mutation is created

Suggested tests:

• mem_save(title="") fails and creates no observation/mutation.
• mem_save(title=" ") fails and creates no observation/mutation.
• engram save "" "content" fails and creates no observation/mutation.
• engram save " " "content" fails and creates no observation/mutation.
• store.AddObservation(Title:"") fails.
• store.AddObservation(Title:" ") fails.
• valid non-empty titles still work.

📌 Impact

This can block project cloud sync with sync_mutation_payload_missing_required_fields and requires manual SQLite repair of both observations.title and frozen sync_mutations.payload.title.

A required JSON schema field is not sufficient here because required:["title"] only requires the key to exist; it does not reject an empty string.

[ricardoarz-dev]

The check you'd want at write time mostly already exists — ValidateSyncMutationPayload in internal/store/diagnostic.go already knows observation upserts need a non-empty title (and prompt upserts need content). Right now it only runs on the doctor/pull side. Reusing it in the write path (store.AddObservation plus the CLI/MCP save entrypoints) would keep the rule in one place instead of duplicating the title check.

[jorocoimbra]

+1 — confirming this bug from an independent setup. Hit it 4 separate times today across 3 projects (cloud sync blocked each time) before tracing the root cause to the same place described here.

Environment

• engram CLI: v1.16.1 (Windows, pre-built binary)
• Plugin: engram@engram v0.1.1 (Claude Code marketplace, current latest)
• Cloud server: self-hosted v1.16.1, container behind Nginx Proxy Manager with HTTPS
• Trigger agent: Claude Code via MCP

What I observed

The agent calls mem_save with title="" whenever the content is something narrative or workflow-like that doesn't naturally have a heading (e.g. "monthly routine: use git log --since ... --until ..."). The MCP tool returns success, the local DB accepts the row, and the failure only surfaces hours later on the next engram sync --cloud.

By that point there can be multiple stuck mutations behind the first blocker, since delete --hard doesn't remove the original — it only adds a delete op to the queue, leaving the bad upsert intact.

Confirmed that none of these recover the project:

• engram cloud upgrade doctor --project X → diagnoses, no fix.
• engram cloud upgrade repair --project X --apply → returns class: blocked, applied: false.
• engram delete <obs_id> --hard → adds another mutation; original blocker remains.
• engram sync --cloud --project X --fix-exported → no effect on this case.
• engram cloud upgrade bootstrap --resume → no effect.

Recovery workaround (preserves content)

For anyone hitting this right now before the fix lands, a non-destructive recovery is to patch both the observation row and the frozen mutation payload directly in SQLite, with the binary stopped:

-- 1. Patch the observation
UPDATE observations
SET title = '<derived title>',
    updated_at = datetime('now')
WHERE id = <obs_id>;

-- 2. Patch the title inside the queued mutation payload
UPDATE sync_mutations
SET payload = json_set(payload, '$.title', '<derived title>')
WHERE project = '<project>' AND seq = <stuck_seq>;

After this, engram sync --cloud --project <project> resumes cleanly and the observation reaches the cloud with full content intact. DELETE on the observation works too but loses the content; the UPDATE path keeps everything.

Why this matters in practice

The agent has no feedback loop: success response from mem_save, no error, no signal to retry with a better title. The user discovers the problem only when cloud sync fails, by which point the queue can have several malformed mutations stacked behind each other. Each one needs the same SQLite intervention.

Pushing the validation up to store.AddObservation (and the MCP/CLI entrypoints) as suggested would close this entirely — happy to test a build with the fix.

[agusabas]

Independent +1 on v1.16.1 (Windows, self-hosted cloud). An architecture observation with real content but title='' (emitted by Claude Code via mem_save on a narrative memory) was one of several rows that blocked a whole project's cloud sync. Unblocking meant backfilling the title in both the observations row and the frozen sync_mutations.payload.

+1 on reusing ValidateSyncMutationPayload (internal/store/diagnostic.go) in the write path so the rule lives in one place (saw PR #467 already targets this). One addition: mem_save's handler (handleSave) guards empty content but not empty title, so a tool-level guard there is worth adding alongside the store-level one.

Saludos desde Santa Fe, Argentina 🇦🇷

[ceeesar13]

+1 — hit this in production today on v1.20.0 (current latest), so it is still reproducible on the newest release. Adding data since the earlier reports were on v1.16.1/v1.18.0.

Environment

• engram CLI v1.20.0, Windows, pre-built binary
• Plugin engram@engram v0.1.1 (Claude Code marketplace)
• Self-hosted cloud server, HTTPS behind Cloudflare
• Agent: Claude Code via MCP

What it cost us

Cloud sync had been silently dead for 3 days across two active projects. Nobody noticed, because every local-facing signal said healthy:

• engram cloud status → configured, auth ready, daemon running
• sync_state.last_acked_seq == last_enqueued_seq for most targets
• sync_state.updated_at kept advancing

The only table that told the truth was sync_chunks, whose newest imported_at was 3 days old. sync_state.updated_at advances on local bookkeeping without anything reaching the network, so it reads as "just synced" when nothing has been delivered. That is worth knowing for anyone diagnosing this.

Measured blast radius

19 of 1565 observations (1.2%) had title = ''. All of them created within a single month; zero before that. The most recent was 8 hours before I started diagnosing, so it is ongoing, not a legacy artifact.

Head-of-line blocking is what makes a 1.2% defect rate a 100% outage. The first bad row sat near the head of each project's queue:

project A: last_acked=4427 → seq 4429 title=''  ✗   36 mutations stuck behind it
project B: last_acked=4461 → seq 4463 title=''  ✗   24 mutations stuck behind it

Several of the blocked rows had perfectly valid titles. They were simply queued behind a bad one.

Confirming @jorocoimbra's trigger

The agent calls mem_save with title="" whenever the content is something narrative or workflow-like that doesn't naturally have a heading.

This matches exactly. Breakdown by type of the 19:

type	empty / total
manual	10 / 295
decision	5 / 220
discovery	2 / 172
bug_fix	1 / 1
bug_finding	1 / 1

Note bug_fix and bug_finding — neither is a canonical type (the documented set is decision, architecture, bugfix, pattern, config, discovery, learning, manual). The same calls that invent a free-form type are the ones that omit title. When a caller is improvising the metadata, the write path is the only thing standing between a malformed record and a frozen queue — and right now it lets it through.

Recovery

@jorocoimbra's SQL workaround is correct and is what worked for us: patch observations.title and the frozen sync_mutations.payload in the same transaction. Two things worth adding:

1. The title had to be written from scratch. It was not lost in serialization — the source observations row never had one either. So this is not recoverable by backfilling from local state; a human (or a model) has to read the content and compose a title. That is also why cloud upgrade repair classified it manual rather than repairable, which lines up with fix(cloud): doctor/repair ignores observations table for empty title/content/type #629.
2. After patching, engram sync --cloud --project <p> drained both queues immediately and cleanly. No further intervention.

PR

Opening a PR against this issue implementing @ricardoarz-dev's suggestion — reusing the rule that ValidateSyncMutationPayload already owns rather than adding a second title check, so the invariant stays in one place.

One finding from implementing it that reviewers should know: stripPrivateTags replaces <private>…</private> with the literal [REDACTED], so a title consisting only of a private tag does not become empty and is still accepted. I pinned that in a test rather than changing it, since rejecting [REDACTED] titles is a separate product decision.

I also found the same gap on Store.UpdateObservation (PATCH /observations/{id} with {"title":""} re-enqueues an equally poisoned upsert). It is the identical one-line guard, but it is a different entrypoint than this issue enumerates, so I left it out to keep the PR to one logical change. Happy to open a separate issue for it if you want it tracked.