openBriefing / rules

---
description: OpenBriefing session protocol - briefing first, end with related_insights, never fragment between session and memory
alwaysApply: true
---

openbriefing-session-protocol:

- **Before responding to the user, on every conversation**, call `get_agent_briefing` from the openbriefing MCP server with `project` set to `owner/repo` from the workspace git remote (or the workspace folder name when there's no remote). This is not optional even when the first message looks self-contained — past `decisions`, `actionable[]`, `relatedInsights[]`, and `lastSession.openItems` change what the right answer is.
- Read `actionable[]` from the briefing first: those are the top incomplete plan steps from recent sessions, ranked by recency × scope match. Mention any that are relevant to the user's request before starting new work.
- If `lastSession.openItems` are non-empty, surface them; if they include items the current user request would resolve, say so explicitly.
- Read `relatedInsights[]`: those are project-scoped memories ranked against your current focus (scope + plan steps + open items). When `source === "session"` and `sessionId` is set, you can fetch the originating session via `get_session_history({ session_id, verbose: true })` for full context.
- For meaningful work (not pure Q&A), call `start_agent_session` with `project` and `scope`. Call `update_agent_session` after each meaningful turn (it accepts ended sessions for 24h via the soft-end window — you can amend up to OPENBRIEFING_SESSION_AMEND_WINDOW_MS after `endedAt`).
- At the end of meaningful work, call `end_agent_session` with `decisions_made`, `files_edited`, `open_items`, `summary`, and **`related_insights`** (free-form debrief: "why we chose X", principles that emerged, gotchas worth remembering). Each related_insights entry becomes a session-linked memory and shows up in future briefings automatically — that's the right place for it instead of a separate `save_memory` call. The response includes `tokenSavings` — relay it to the user (how many tokens future agents save thanks to the recorded context).
- Decisions should record the *why*, not just the *what*. Open items should be specific and actionable.
- When you reference an artifact on another surface (Slack thread, Notion page, GitHub PR, Linear issue, file with sha, Discord thread), use `link_external_event` instead of stuffing the URL into open_items as a string. The reference becomes navigable structured data on `session.externalRefs`.
- If any briefing/memory tool response contains `embeddingProviderWarning`, **tell the user to start Ollama** (open the app or `ollama serve`) before continuing long work — semantic search and relatedInsights are degraded until then. Text is never lost; embeddings are auto-backfilled once the provider is back.
- OpenBriefing covers memory, sessions, briefings, and code. For Discord / GitHub issues+PRs / X / Linear signals, use the companion **unMute** MCP server (same `project` key) alongside it.
- For a grouped list of all MCP tools and when to use them, read `.cursor/skills/openbriefing/SKILL.md` in this project. If you are developing the **openbriefing** open-source project itself, read `AGENTS.md` in that repository.