capture-learnings

# Capture Learnings This is background knowledge, not a slash command. **Organization learnings and your personal memory index are loaded at the start of every conversation, including Slack/integration turns.** Capture durable context proactively when you learn something worth remembering. ## How to Read & Write Memories Memories are stored as **resources** in the SQL database, not as files on disk. - **Team/organization knowledge:** shared `LEARNINGS.md`. Read it first, merge the new fact, then write the full updated file with the `resources` tool using `scope: "shared"`. Shared scope resolves to the active organization; it must never leak to another organization in the same deployment. - **Personal knowledge:** `memory/MEMORY.md` plus `memory/<name>.md`, written with `save-memory`. - **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."` - **Read a memory:** `resource-read --path memory/<name>.md` - **Delete a memory:** `delete-memory --name <name>` - **List all memories:** `resource-list --prefix memory/` ## Memory Types | Type | Use for | |------|---------| | `user` | Preferences, role, personal context, contacts | | `feedback` | Corrections, confirmed approaches, things to avoid or repeat | | `project` | Ongoing work context, decisions, deadlines, status | | `reference` | Pointers to external systems, URLs, API details | ## When to Capture Follow the user's personal `memory/INSTRUCTIONS.md` when deciding what to preserve or leave out. It is loaded automatically with the user's personal `AGENTS.md` instructions. At the natural stopping point of a meaningful multi-turn task, review the conversation for durable preferences, corrections, decisions, conventions, or project context that would improve a future thread. Save only new, supported facts; completed task details and temporary debugging notes stay in the thread. ### Team and organization knowledge (`LEARNINGS.md`, shared scope) - Canonical destinations and workflows (for example, which Content database receives a type of Slack request) - Required intake fields, ownership, prioritization conventions, metric definitions, and approved terminology - Durable external references that the whole team needs, including the canonical page/database URL - Corrections or decisions that should affect every organization member's future Slack and app conversations Store the fact and a concise provenance link when available. Do not paste full private conversations, customer data, credentials, or secrets into learnings. Put stable always-on policy in shared `AGENTS.md`; put learned facts and evolving conventions in shared `LEARNINGS.md`. ### User Preferences & Memory (`user`) - **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short" - **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone") - **Workflow preferences** — "always CC my assistant", "I like to review before sending" - **Role and expertise** — "I'm a data scientist", "new to React" ### Feedback & Corrections (`feedback`) - **Corrections** — user says "no, do it this way" → capture the right way - **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect") - **Repeated friction** — you hit the same issue twice; save it ### Project Context (`project`) - **Ongoing work** — who is doing what, why, by when - **Decisions** — why something is done a certain way - **Status** — current state of initiatives ### References (`reference`) - **External systems** — "bugs are tracked in Linear project INGEST" - **URLs** — dashboards, documentation, tools - **API quirks** — undocumented behavior, version-specific gotchas ### Don't Capture - Things obvious from reading the code - Standard language/framework behavior - Temporary debugging notes - Anything already in AGENTS.md, shared LEARNINGS.md, or skills - Ephemeral task details (use tasks/plans instead) ## Key Rules 1. **Save proactively — don't ask permission.** When you learn something durable, save it immediately at the correct scope. 2. **Choose scope by audience.** Organization workflow or reference → shared `LEARNINGS.md`; one person's preference/context → personal memory. 3. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump 4. **Read before updating** — if a memory exists, read it first and merge, don't overwrite 5. **Make memories retrievable** — concise descriptions include names, relationships, and common wording the user may use to ask for that memory; the index powers automatic recall. 6. **Keep descriptions concise** — the index is loaded every conversation 7. **Memories are SQL-backed** — they persist across sessions and are not in git; still minimize sensitive content ## Graduation When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill: - Saving a personal memory is lightweight (auto-apply, personal scope) - Shared LEARNINGS.md is the lightweight organization knowledge layer - Updating AGENTS.md or a skill is heavier (affects all users/agents)