--- name: lore description: >- Use your organization's Lore Index memory — governed, vendor-neutral team knowledge — over the MCP tools lore_bootstrap, lore_search, lore_get, lore_propose, and lore_whoami. Load the guidance pack at session start, search Lore Index before answering org-specific questions (policies, conventions, contacts, glossary, "how we do X here"), treat MUST entries as binding, cite the entry ids you rely on, and propose new knowledge instead of assuming write access. Triggers whenever the user asks about company/team norms, internal processes, tooling choices, or facts that are not general knowledge. --- # Lore Index — your organization's memory Lore Index is a governed store of an organization's durable knowledge: instructions, preferences, facts, contacts, and glossary terms. It exists so agents apply the team's real conventions instead of guessing. Lore Index is **governance, not extraction**: entries are human-curated and scoped, and you should treat what it returns as authoritative for this org. You reach Lore Index through five MCP tools. All results are plain text. Be token-frugal: pull the small pack once, then search narrowly. ## When to use Lore Index Use it whenever a question is **organization-specific** and the answer is not general world knowledge, e.g.: - "What's our policy on X?" (expenses, PII, code review, on-call…) - "Which tool/library/style do we use for Y?" (IaC, package manager, language settings) - "Who owns Z / who do I contact about…?" - "What does mean here?" - Any task where a team convention would change how you answer or act. If the user's request could be shaped by a team norm, **search before you answer**. Do not invent a policy; if Lore Index has nothing, say so. ## Session start: bootstrap once At the beginning of a working session (or when you first realize org context matters), call: ``` lore_bootstrap() ``` It returns a compact markdown **pack**: the active `MUST` and `SHOULD` guidance for your scopes, grouped by type, each line ending with `(id:…)`. The pack is capped (~1,500 tokens) and cached server-side, so it is cheap. Call it **once** per session and keep it in mind — do **not** call bootstrap repeatedly. `MUST` entries are **binding constraints** — follow them even if they conflict with a general best practice or your default behavior. `SHOULD` entries are strong defaults; deviate only with a clear reason. The pack is a **point-in-time snapshot**. Entries may be edited, added, or retired after you bootstrapped, so it can go stale in a long session. Treat it as your standing context, but for any **specific** question, run a fresh `lore_search` rather than trusting the cached pack — search always reads the current, active entries. ## Answering: search, then get For anything not already covered by the pack, search: ``` lore_search(query, tags?, type?, limit=5) ``` Returns dense lines: `id | priority | title | first ~200 chars of body`. Ranked by relevance with a priority boost (must > should > context) and scoped to what you're allowed to see. Tips: - Use plain keywords ("expenses receipts", "terraform state", not full sentences). - Narrow with `type` (`instruction | preference | fact | contact | glossary`) or `tags` when you know them. - Keep `limit` small (default 5). Search again with better terms rather than pulling a huge list. When a search line looks relevant but you need the whole thing, fetch it: ``` lore_get(id) ``` Returns the full body plus a provenance line `[source: …, status: …]` so you can judge how much to trust it and whether it's current. Prefer `active` entries. ## Cite what you apply When Lore Index guidance shapes your answer or action, **cite the entry id(s)** you relied on, e.g. "Per Lore Index `01J…` (MUST: route infra changes through PR review), I've opened a PR rather than pushing directly." This keeps your reasoning auditable and lets humans trace decisions back to the governing rule. ## Scope awareness Entries are scoped: `org` (everyone), `team:`, `role:`, or `user:`. You only ever see entries in **your** scopes — search and the pack are filtered for you automatically, so you never need to reason about other teams' rules. Narrower scopes take precedence over broader ones (user > role > team > org) when guidance overlaps. Call `lore_whoami()` if you need to know who you're acting as, which teams/roles you're in, and which scopes you may write to. ## Propose — never assume write You may **not** silently write to org memory. When you learn something durable that belongs in Lore Index (a stable convention, a corrected fact, a new contact), propose it: ``` lore_propose(type, title, body, scope, tags) ``` - `lore_propose` **always** creates a **pending_review** entry that a human approves or rejects — regardless of your key's scope. It never writes to org memory directly. The tool returns the new id and a **review URL**. - (Direct/active writes exist only on the REST API for write-scoped keys; over MCP, propose means propose.) - You can only target a scope you can already read. Pick the **narrowest** scope that's correct (a team preference is `team:`, not `org`). Good proposals are: durable (not a one-off), concise (bodies are capped at 1,000 chars), and actionable. Use an imperative title for `instruction` entries ("Route infra changes through PR review"). Do **not** propose secrets, customer PII, or transient chatter. ### When to propose vs. when not to - Propose: "The team consistently prefers X over Y", a confirmed policy, a stable ownership/contact fact, a glossary term you had to look up. - Don't propose: guesses, anything you're unsure is a real norm, duplicates of existing entries (search first), or anything time-boxed to one task. ## Token frugality Lore Index is designed to be cheap; keep it that way: - Bootstrap once per session; rely on the cached pack for standing context, but `lore_search` for specific answers (fresh, not stale). - Prefer one targeted `lore_search` over many broad ones. - `lore_get` only the entries you actually need in full. - Don't paste whole entries back to the user verbatim unless asked — summarize and cite the id. ## Quick reference | Tool | Use it to… | | --- | --- | | `lore_bootstrap()` | Load the guidance pack at session start. | | `lore_search(query, tags?, type?, limit=5)` | Find relevant entries before answering. | | `lore_get(id)` | Read one entry in full, with provenance. | | `lore_propose(type, title, body, scope, tags)` | Submit new knowledge to the review queue (always pending_review). | | `lore_whoami()` | See your identity, teams, roles, writable scopes. | **Golden rules:** bootstrap once at start · search (fresh) before answering org questions · MUST is binding · cite ids · propose always goes to human review · stay in scope · be frugal.