Engram Onboarding

Use this skill to establish an engram memory session in a repository from scratch. Follow the steps in order. Each step builds on the previous one.

When to Use

• First agent session in a repo that has engram running
• Resuming work after a long gap (re-scan and reload context)
• New agent picking up work mid-project

Prerequisites

• Engram MCP server is reachable (check ENGRAM_URL or the MCP transport config)
• You have a path (absolute path to the repo root)

Step 1 — Bootstrap: Load Prior Context

Call memory_build_context to retrieve relevant memories and establish prior context before doing any work.

{
  "name": "memory_build_context",
  "arguments": {
    "query": "project context decisions architecture setup",
    "strategy": "balanced",
    "limit": 20,
    "depth": 2,
    "timeframe": "all"
  }
}

On success: you receive a structured prompt context from stored memories. Read it before proceeding — it tells you what was done in prior sessions.

On failure:

• connection refused → engram server is not running. Start it or check ENGRAM_URL.
• Empty result → no prior memories exist. This is a fresh start. Continue to Step 2.
• Any other error → report to the user and stop. Do not proceed without confirming server connectivity.

Step 2 — Scan: Discover Existing Memories

Call memory_scan_project to index AI instruction files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) in the repo and surface any memories already stored.

{
  "name": "memory_scan_project",
  "arguments": {
    "path": "/absolute/path/to/repo",
    "extract_sections": true
  }
}

Interpret the result:

• Memories created → read the returned summaries. Note workspaces already in use.
• No files found → this is a fresh start. Continue to workspace setup.
• error → log the error and continue. A scan failure does not block the session.

Step 3 — Workspace Setup

List existing workspaces to avoid creating duplicates.

{
  "name": "workspace_list",
  "arguments": {}
}

For a typical engineering repo, ensure these workspaces exist. Workspaces are created implicitly when you write a memory with "workspace": "<name>" — there is no separate creation call.

If a workspace from the table above is missing from workspace_list output, it will be created automatically when you write the first memory into it in Step 4.

Step 4 — First Memory: Record the Onboarding Event

Store a memory documenting that onboarding ran and what you found.

{
  "name": "memory_create",
  "arguments": {
    "content": "Engram onboarding completed. Scanned project, found N existing memories across M workspaces. Workspaces initialized: decisions, bugs, architecture, tasks, onboarding.",
    "memory_type": "episodic",
    "workspace": "onboarding",
    "importance": 0.7,
    "tags": ["onboarding", "session-start", "setup"]
  }
}

Replace N and M with the actual counts from Step 2.

Field guidance:

• memory_type: use "episodic" for events, "decision" for choices made, "procedural" for how-to knowledge, "note" for general observations, "context" for background information, "learning" for lessons learned
• importance: 0.9–1.0 for critical decisions, 0.6–0.8 for context, 0.3–0.5 for low-priority notes
• tags: always include at least one domain tag and one lifecycle tag (e.g. "session-start")

Step 5 — Search: Verify Retrieval Works

Confirm that the memory you just created (and any prior ones) are retrievable.

{
  "name": "memory_search",
  "arguments": {
    "query": "onboarding session setup workspaces",
    "workspace": "onboarding",
    "rerank": true,
    "limit": 5
  }
}

Expected result: the memory from Step 4 appears in the top results.

If nothing is returned:

• Wait 1–2 seconds and retry (indexing may be async).
• Try without workspace to search across all scopes.
• If still empty, report to the user — retrieval may need investigation.

Cross-workspace search example:

{
  "name": "memory_search",
  "arguments": {
    "query": "architecture decisions database",
    "rerank": true,
    "limit": 10
  }
}

Step 6 — Session Close: Handoff Summary

When the session ends, call harness_handoff to persist a structured handoff for the next agent. Then call session_land to generate a checkpoint memory with session summary.

harness_handoff (structured handoff packet):

{
  "name": "harness_handoff",
  "arguments": {
    "current_goal": "Completed initial onboarding — workspaces set up, first memories stored",
    "next_steps": [
      "Continue storing decisions and findings as memories",
      "Run memory_search before starting each new task",
      "Check decisions workspace before making architectural choices"
    ]
  }
}

session_land (checkpoint memory for continuity):

{
  "name": "session_land",
  "arguments": {
    "session_id": "<session_id from your session context>",
    "workspace": "onboarding",
    "summary": "Onboarding complete. Workspaces initialized: decisions, bugs, architecture, tasks, onboarding. No prior memories found — fresh install.",
    "next_session_hints": [
      "Run memory_build_context before starting work",
      "Check decisions workspace before making architectural choices"
    ]
  }
}

Write the summary in imperative past tense: what was done, what was found, what the next agent needs to know.

Quick Reference: Common Follow-Up Calls

Store a decision:

{
  "name": "memory_create",
  "arguments": {
    "content": "Chose PostgreSQL over SQLite for multi-writer workload support.",
    "memory_type": "decision",
    "workspace": "decisions",
    "importance": 0.9,
    "tags": ["decision", "database", "architecture"]
  }
}

Record a bug:

{
  "name": "memory_create",
  "arguments": {
    "content": "Race condition in batch processor when concurrency > 4. Workaround: set BATCH_CONCURRENCY=4 until #123 is fixed.",
    "memory_type": "note",
    "workspace": "bugs",
    "importance": 0.85,
    "tags": ["bug", "concurrency", "workaround"]
  }
}

Resume from prior session:

{
  "name": "memory_search",
  "arguments": {
    "query": "last session carry-overs blockers",
    "workspace": "tasks",
    "rerank": true,
    "limit": 5
  }
}

Error Handling Summary