Session Summaries

📝 Session Lifecycle (Briefings & Summaries)

Tip

Value Proposition: The Session Lifecycle guarantees cross-session continuity and zero-loss agent handoffs by creating a structured, machine-actionable chain of context for every session, branch, and thread.

---

✨ Why The Session Lifecycle Matters

Traditional AI interactions suffer from amnesia, forcing you to repeatedly re-establish context. The Session Lifecycle permanently solves this by weaving a continuous, machine-actionable chain of intelligence across every session and thread.

---

📋 The Session Briefing

When starting a new session, users can trigger the load-briefing prompt to have the agent read the Memory Journal Briefing via the memory://briefing (or memory://briefing/{+repo}) resource.

Tip

Mid-Session Context Recovery: If an agent loses track of the active project_number or workspace_id mid-session, query the lightweight memory://agent-id / memory://agent-id/{+repo} (or memory://agent-context / memory://agent-context/{+repo}) resource rather than reloading the full memory://briefing.

The briefing assembles a live contextual snapshot, including:

• Journal Health & Guardrails: memory://briefing surfaces the Journal Health orphan alert (recommending mj-mcp-optimize / optimize-journal when orphan ratio exceeds 20%) and deprecation warnings, while memory://instructions enforces the Server Bug Protocol (mcp-heal).
• GitHub State: Active PRs, CI monitor status, and issue counts.
• Recent Journal Context: In memory://briefing, surfaces the latest session-summary entry ID, timestamp, and headline preview so the agent can inspect #id for ## Unfinished / Blocked and ## Context for Next Session.
• Git History & Velocity: Recent Git commits are displayed with their impact/confidence scores, while briefingImportanceThreshold filters low-importance personal journal entries in the briefing (session-summary-tagged entries automatically bypass briefingImportanceThreshold).
• Active Workspace Details: Active projects, environment configurations, and metrics.

---

🚀 Bootstrapping a Workspace

Before you can effectively record session summaries for a project, the workspace must be registered. Workspaces are not implicitly created; they must be explicitly bootstrapped to establish the tracking metadata and boundaries.

You can bootstrap a workspace using:

• CLI: memory-journal-mcp project create "my-project" --path "/path/to/repo" --number 123 [--db <path>]
• MCP Code Mode: mj.admin.registerProject({ name: "my-project", absolute_path: "/path/to/repo", project_number: 123 })

Once bootstrapped, the workspace_id is automatically tracked and injected into your session briefings.

---

🛠️ How to Create a Session Summary

At the end of a productive session, agents should record a session summary. You can create a personal summary or a team summary if you're collaborating in a shared workspace.

Option 1: MCP Code Mode / MCP Tool (Recommended)

Execute directly in Code Mode via mj.core.createEntry (create_entry) or mj.team.teamCreateEntry (team_create_entry):

await mj.core.createEntry({
  content: "## Accomplished\n- ...\n\n## Unfinished / Blocked\n- None\n\n## Context for Next Session\n- ...\n\n## Commits\n- `<sha>`",
  entry_type: "retrospective",
  tags: ["session-summary", "architecture"],
  auto_context: { type: "session-commits", commits: ["<sha>"], branch: "main" },
  impact_score: 0.8,
  trust_score: 0.9,
  validation_status: "passed",
  // Note: for full team session summaries that persist auto_context, session_id, and relationships,
  // call mj.team.teamCreateEntry (team_create_entry) directly instead of share_with_team: true.
});

Option 2: CLI Scratch File (YAML Frontmatter or --metadata)

memory-journal-mcp entry create --file <scratch_dir>/session-summary.md natively parses YAML frontmatter (--- ... ---) directly from the Markdown file (or accepts a companion --metadata JSON file):

Standard Session Summary:

memory-journal-mcp entry create \
  --file <scratch_dir>/session-summary.md \
  [--metadata <scratch_dir>/metadata.json]

Team Session Summary: If you are prompted to run the team-session-summary prompt for a shared workspace, simply append the --team flag:

memory-journal-mcp entry create --team \
  --file <scratch_dir>/session-summary.md \
  [--metadata <scratch_dir>/metadata.json]

Required Fields & Metadata (metadata.json / YAML Frontmatter)

To ensure high-fidelity context retrieval, every session summary MUST define the following fields accurately:

• type: Must be exactly "retrospective".
• tags: Must include "session-summary", alongside 2-3 relevant domain tags (e.g., "architecture", "refactor").
• project: The numeric ID or repository name of the active workspace (optional, auto-resolved from the active workspace).
• impact: Decimal score (0.0 - 1.0) analyzing blast radius (e.g., 0.9+ for core architecture, 0.1 for simple docs).
• trust: Decimal score (0.0 - 1.0) analyzing testing rigor (e.g., 0.3-0.5 for unverified, 0.8-1.0 for rigorously tested).
• validation_status: "passed", "none", or "failed". Note: The schema DB field 'validation_status' (passed | none | failed) is distinct from the commit prompt's input argument 'validation' (none | lint | full).
• auto_context: A concise JSON payload providing machine-readable commit provenance. Must EXACTLY match: {"type":"session-commits","commits":["<sha>"],"branch":"<branch_name>","pr":<number>} (auto_context.commits also powers memory://commits/{project_number}, memory://commits/{project_number}/by-issue, and memory://commits/{project_number}/by-pr).
• relationships: An array of links to previous entries (e.g., [{"targetId": 123, "relationType": "resolved"}]; note that create_entry also auto-heals target_id/relation_type). Always link to the previous session summary to maintain the causal chain.

Tip

create_entry (personal journal) populates entry_anchors via resolveEntryAnchors from explicit anchors or modified files automatically extracted from auto_context.commits (up to 10 commits and 25 files), and validates the 4 required Markdown headers (## Accomplished, ## Unfinished / Blocked, ## Context for Next Session, ## Commits) whenever the "session-summary" tag is present.

Option 3: MCP Prompt (/session-summary or /team-session-summary)

You can also invoke the /session-summary or /team-session-summary MCP prompt to guide the agent through generating a structured retrospective. Remember that CreateEntrySchema and TeamCreateEntrySchema require all 4 headers (including ## Commits) in content, and for full team session summaries that persist auto_context, session_id, and relationships, prefer mj.team.teamCreateEntry (team_create_entry).

📏 Size Limits

See Schema for all size and length constraints.

---

🏗️ The Golden Structure (session.md)

For maximum readability and parsing efficiency by future agents, the markdown content of a Session Summary MUST follow this EXACT structure. Do not add extraneous headers, introductions, or top-level sections.

## Accomplished
- [Concrete item 1 done this session]
- [Concrete item 2 done this session]

## Unfinished / Blocked
- [Remaining items, dependencies pending, or "None"]

## Context for Next Session
- [Entry IDs, branch names, PR numbers, pending decisions]

## Commits
- [Commit SHAs or "None"]

Warning

Strict Formatting Rule Do NOT add sections like "## Summary", "## Overview", or "## Notes". Always write all 4 top-level Markdown headers (## Accomplished, ## Unfinished / Blocked, ## Context for Next Session, ## Commits) in content when creating an entry with the "session-summary" tag. CreateEntrySchema and TeamCreateEntrySchema enforce the 4-header structure on both MCP and Code Mode tool paths (in Code Mode mj_execute_code, healSessionSummaryContent also normalizes common header synonyms and appends - None. or - None placeholders if a section was omitted, whereas direct MCP create_entry / team_create_entry calls auto-heal entry_type: "session-summary" -> "retrospective" + tag "session-summary" and strictly validate all 4 headers), while the standalone CLI (memory-journal-mcp entry create) writes directly via DatabaseAdapter.createEntry so CLI callers must provide the 4 headers directly.

---

🚫 When NOT to Create a Summary

Session Summaries are designed to track substantive momentum. Do NOT create a session summary if:

• You ran a testing pass and everything passed, but no code was changed.
• You merely viewed files or explored architecture without making decisions or edits.
• The session was aborted or failed without producing actionable insights.

Keep the signal-to-noise ratio high!