Engram specs "truncated"

[Tavo5691]

I'm using engram and sometimes I see the sub-agents (sdd-apply in this case) show messages like these

I also checked with engram tui the latest observations and

Could this be caused by a config on my side?

This is causing the agent to reach for context in the codebase or in some design docs I have in the repo, but the specs should have what it needs.

I'm using Windows 11 (WSL), OpenCode, Claude Sonnet 4.6 and engram.

[Alan-TheGentleman]

Root Cause

mem_search returns 300-char previews by design (token efficiency). The correct flow is:

1. mem_search("sdd/{change}/spec") → get the observation ID
2. mem_get_observation(id) → get the full untruncated content

Sub-agents (especially Sonnet) sometimes skip step 2 and treat the 300-char preview as the complete spec. Since it looks incomplete, they compensate by searching the codebase/design docs — which defeats the purpose of having specs in engram.

This is NOT a config issue. The content is stored in full (50k char limit). The truncation happens only in the mem_search response layer.

What was fixed in Engram (v1.9.5 — released)

PR: Gentleman-Programming/engram@0ba0984

Two hints added to mem_search output so models can't miss the truncation:

1. Per-result marker — any result with content > 300 chars gets:

   [truncated — use mem_get_observation(id) for full content]
   

2. Footer hint — when any result was truncated:

   ---
   ⚠ Content previews above are truncated to 300 chars. Call mem_get_observation(id: <ID>) to retrieve full content.
   

What remains to be done in agent-teams-lite (skills side)

Fix 1: Front-load a warning in sub-agent prompts

In the orchestrator's sub-agent launch prompt, add this BEFORE the artifact read steps:

CRITICAL: mem_search returns 300-char PREVIEWS, not full content.
You MUST call mem_get_observation(id) for EVERY artifact.
If you skip this step, you will work with incomplete specs and produce wrong code.

Models read top-down — front-loaded warnings are more effective than buried instructions.

Fix 2: Restructure the read protocol in SDD skills

Current format (interleaved, easy to skip step 2):

1. mem_search("sdd/{change}/spec") → get ID
2. mem_get_observation(id) → full spec
3. mem_search("sdd/{change}/design") → get ID
4. mem_get_observation(id) → full design

Proposed format (grouped, structurally harder to skip):

STEP 1 — SEARCH (get IDs only, content is truncated):
  a. mem_search("sdd/{change}/tasks")   → save ID
  b. mem_search("sdd/{change}/spec")    → save ID
  c. mem_search("sdd/{change}/design")  → save ID

STEP 2 — RETRIEVE FULL CONTENT (mandatory for each):
  a. mem_get_observation(id: tasks_id)  → full tasks
  b. mem_get_observation(id: spec_id)   → full spec
  c. mem_get_observation(id: design_id) → full design

DO NOT use search previews as source material.

Affected files

All SDD skills that read artifacts:

• sdd-apply/SKILL.md (lines 30-37)
• sdd-spec/SKILL.md
• sdd-design/SKILL.md
• sdd-tasks/SKILL.md
• sdd-verify/SKILL.md
• sdd-archive/SKILL.md
• _shared/persistence-contract.md
• _shared/engram-convention.md

Plus the orchestrator prompt template in the CLAUDE.md SDD section.