Remember - Store Decisions and Patterns
Filesystem vs MCP memory (Opus 5.5 guidance, CC 2.1.111+): Opus 5.5 reads filesystem memory reliably across multi-session work. Use that to your advantage:
- Short-lived handoff state (current phase, task in-progress, pending approvals) →
.claude/chain/*.json files. Small, structured, session-scoped.
- Durable auto-memory (user facts, feedback, project conventions) →
~/.claude/projects/<slug>/memory/*.md files with a one-line index in MEMORY.md. Read on every session start.
- Cross-session knowledge graph (typed entities + relations for query traversal) → MCP memory server (this skill's default path). Best when future sessions will search for patterns.
The three are complementary, not alternatives. Prefer fs for anything you'd want to grep; prefer MCP for anything you'd want to traverse.
Store important decisions, patterns, or context in the knowledge graph for future sessions. Supports tracking success/failure outcomes for building a Best Practice Library.
Argument Resolution
TEXT = "$ARGUMENTS" # Full argument string, e.g., "We use cursor pagination"
FLAG = "$ARGUMENTS[0]" # First token — check for --success, --failed, --category, --agent
# Parse flags from $ARGUMENTS[0], $ARGUMENTS[1] etc. (CC 2.1.59 indexed access)
# Remaining tokens after flags = the text to remember
Architecture
The remember skill uses knowledge graph as storage:
- Knowledge Graph: Entity and relationship storage via
mcp__memory__create_entities and mcp__memory__create_relations. These tools come from a memory MCP server that OrchestKit does not bundle: configure one in the user or project scope first (for example @modelcontextprotocol/server-memory) and confirm it with claude mcp list. Without it, every graph step here does nothing.
Benefits:
- Free and local once the memory server is configured
- Explicit relationship queries (e.g., "what does X use?")
- Cross-referencing between entities
- No cloud dependency
Automatic Entity Extraction:
- Extracts capitalized terms as potential entities (PostgreSQL, React, pgvector)
- Detects agent names (database-engineer, backend-system-architect)
- Identifies pattern names (cursor-pagination, connection-pooling)
- Recognizes "X uses Y", "X recommends Y", "X requires Y" relationship patterns
Usage
Store Decisions (Default)
remember <text>
remember --category <category> <text>
remember --success <text> # Mark as successful pattern
remember --failed <text> # Mark as anti-pattern
remember --success --category <category> <text>
# Agent-scoped memory
remember --agent <agent-id> <text> # Store in agent-specific scope
remember --global <text> # Store as cross-project best practice
Flags
| Flag |
Behavior |
| (default) |
Write to graph |
--success |
Mark as successful pattern |
--failed |
Mark as anti-pattern |
--category <cat> |
Set category |
--agent <agent-id> |
Scope memory to a specific agent |
--global |
Store as cross-project best practice |
Categories
decision - Why we chose X over Y (default)
architecture - System design and patterns
pattern - Code conventions and standards
blocker - Known issues and workarounds
constraint - Limitations and requirements
preference - User/team preferences
pagination - Pagination strategies
database - Database patterns
authentication - Auth approaches
api - API design patterns
frontend - Frontend patterns
performance - Performance optimizations
Outcome Flags
--success - Pattern that worked well (positive outcome)
--failed - Pattern that caused problems (anti-pattern)
If neither flag is provided, the memory is stored as neutral (informational).
Workflow
1. Parse Input
Check for --success flag → outcome: success
Check for --failed flag → outcome: failed
Check for --category <category> flag
Check for --agent <agent-id> flag → agent_id: "ork:{agent-id}"
Check for --global flag → use global user_id
Extract the text to remember
If no category specified, auto-detect from content
2. Auto-Detect Category
| Keywords |
Category |
| chose, decided, selected |
decision |
| architecture, design, system |
architecture |
| pattern, convention, style |
pattern |
| blocked, issue, bug, workaround |
blocker |
| must, cannot, required, constraint |
constraint |
| pagination, cursor, offset, page |
pagination |
| database, sql, postgres, query |
database |
| auth, jwt, oauth, token, session |
authentication |
| api, endpoint, rest, graphql |
api |
| react, component, frontend, ui |
frontend |
| performance, slow, fast, cache |
performance |
3. Extract Lesson (for anti-patterns)
If outcome is "failed", look for:
- "should have", "instead use", "better to"
- If not found, prompt user: "What should be done instead?"
4-6. Extract Entities and Create Graph
Extract entities (Technology, Agent, Pattern, Project, AntiPattern) from the text, detect relationship patterns ("X uses Y", "chose X over Y", etc.), then create entities and relations in the knowledge graph.
7. Confirm Type + Scope (AskUserQuestion — M118 #1466)
Auto-classification is best-effort. Before writing, ask the user to confirm both the memory type and the persistence scope. Pre-select the auto-detected type as the default option when the classifier is confident (≥0.9):
# Skip when the invocation already specifies type and scope:
# remember --type=preference --global → skip, use those values
# remember --session → skip, no persistence
#
# Otherwise, ask both:
AskUserQuestion(questions=[
{"question": "What type of memory?",
"header": "Type",
"options": [
{"label": "Preference", "description": "How I like to work (style, format, tooling)"},
{"label": "Project fact", "description": "State of THIS codebase (decisions, constraints)"},
{"label": "Reference", "description": "External system pointer (URL, doc, dashboard)"},
{"label": "Feedback", "description": "Correction to future behavior — applied as a rule"}
]},
{"question": "Apply to?",
"header": "Scope",
"options": [
{"label": "This project (default)", "description": "Scoped to .claude/projects/<this-project>/memory/"},
{"label": "All projects (global)", "description": "User-level memory at ~/.claude/memory/"},
{"label": "This session only", "description": "Print to context but don't persist"}
]}
])
Default selection rules:
- If auto-detected category maps to one of the 4 type options with confidence ≥0.9, that option is pre-selected (the user can still override).
- "This project" is always the scope default.
- "This session only" returns immediately without writing — useful when the user wants to surface a fact for the conversation but not commit it.
Global memory writes route to ~/.claude/memory/<filename>.md instead of the project-local memory directory. The MEMORY.md index is updated in whichever scope was selected (project- or user-level).
Load entity extraction rules, type assignment, relationship patterns, and graph creation examples: Read("references/graph-operations.md")
7. Confirm Storage
Display confirmation using the appropriate template (success, anti-pattern, or neutral) showing created entities, relations, and graph stats.
Load output templates and examples: Read("references/confirmation-templates.md")
File-Based Memory Updates
When updating .claude/memory/MEMORY.md or project memory files:
- PREFER Edit over Write to preserve existing content and avoid overwriting
- Use stable anchor lines:
## Recent Decisions, ## Patterns, ## Preferences
- See the
memory skill's "Permission-Free File Operations" section for the full Edit pattern
- This applies to the calling agent's file operations, not to the knowledge graph operations above
References
Load on demand with Read("references/<file>"):
| File |
Content |
category-detection.md |
Auto-detection rules for categorizing memories (priority order) |
graph-operations.md |
Entity extraction, type assignment, relationship patterns, graph creation |
confirmation-templates.md |
Output templates (success, anti-pattern, neutral) and usage examples |
Related Skills
ork:memory - Search, load, sync, visualize (read-side operations)
Error Handling
- Knowledge graph unavailable → show configuration instructions
- Empty text → ask user for content; text >2000 chars → truncate with notice
- Both --success and --failed → ask user to clarify
- Entity extraction fails → create generic Decision entity; relation fails → create entities first, retry
1---2name: remember-23license: MIT4compatibility: "Claude Code 2.1.277+. Requires memory MCP server."5description: "Write-side memory: stores decisions, patterns and outcomes in the knowledge graph. Use when something worth keeping was learned or decided. To search use memory; to consolidate use dream."6argument-hint: "[decision-or-pattern]"7context: inherit8user-invocable: true9allowed-tools: "Read Grep Glob Bash AskUserQuestion mcp__memory__create_entities mcp__memory__create_relations mcp__memory__add_observations mcp__memory__search_nodes"10effort: low11model: haiku12metadata:13 source: https://skillmd.com/skills/yonatangross/remember-214 category: workflow-automation15 mcp-server: memory16 version: "3.0.1"17 author: "OrchestKit"18 complexity: "low"19 tags: "memory, decisions, patterns, best-practices, graph-memory"20---2122# Remember - Store Decisions and Patterns2324> **Filesystem vs MCP memory (Opus 5.5 guidance, CC 2.1.111+):** Opus 5.5 reads filesystem memory reliably across multi-session work. Use that to your advantage:25> - **Short-lived handoff state** (current phase, task in-progress, pending approvals) → `.claude/chain/*.json` files. Small, structured, session-scoped.26> - **Durable auto-memory** (user facts, feedback, project conventions) → `~/.claude/projects/<slug>/memory/*.md` files with a one-line index in `MEMORY.md`. Read on every session start.27> - **Cross-session knowledge graph** (typed entities + relations for query traversal) → MCP memory server (this skill's default path). Best when future sessions will *search* for patterns.28>29> The three are complementary, not alternatives. Prefer fs for anything you'd want to grep; prefer MCP for anything you'd want to traverse.3031Store important decisions, patterns, or context in the knowledge graph for future sessions. Supports tracking success/failure outcomes for building a Best Practice Library.3233## Argument Resolution3435```python36TEXT = "$ARGUMENTS" # Full argument string, e.g., "We use cursor pagination"37FLAG = "$ARGUMENTS[0]" # First token — check for --success, --failed, --category, --agent38# Parse flags from $ARGUMENTS[0], $ARGUMENTS[1] etc. (CC 2.1.59 indexed access)39# Remaining tokens after flags = the text to remember40```4142## Architecture4344The remember skill uses **knowledge graph** as storage:45461. **Knowledge Graph**: Entity and relationship storage via `mcp__memory__create_entities` and `mcp__memory__create_relations`. These tools come from a `memory` MCP server that OrchestKit does not bundle: configure one in the user or project scope first (for example `@modelcontextprotocol/server-memory`) and confirm it with `claude mcp list`. Without it, every graph step here does nothing.4748**Benefits:**49- Free and local once the memory server is configured50- Explicit relationship queries (e.g., "what does X use?")51- Cross-referencing between entities52- No cloud dependency5354**Automatic Entity Extraction:**55- Extracts capitalized terms as potential entities (PostgreSQL, React, pgvector)56- Detects agent names (database-engineer, backend-system-architect)57- Identifies pattern names (cursor-pagination, connection-pooling)58- Recognizes "X uses Y", "X recommends Y", "X requires Y" relationship patterns5960## Usage6162### Store Decisions (Default)63```64remember <text>65remember --category <category> <text>66remember --success <text> # Mark as successful pattern67remember --failed <text> # Mark as anti-pattern68remember --success --category <category> <text>6970# Agent-scoped memory71remember --agent <agent-id> <text> # Store in agent-specific scope72remember --global <text> # Store as cross-project best practice73```7475## Flags7677| Flag | Behavior |78|------|----------|79| (default) | Write to graph |80| `--success` | Mark as successful pattern |81| `--failed` | Mark as anti-pattern |82| `--category <cat>` | Set category |83| `--agent <agent-id>` | Scope memory to a specific agent |84| `--global` | Store as cross-project best practice |8586## Categories8788- `decision` - Why we chose X over Y (default)89- `architecture` - System design and patterns90- `pattern` - Code conventions and standards91- `blocker` - Known issues and workarounds92- `constraint` - Limitations and requirements93- `preference` - User/team preferences94- `pagination` - Pagination strategies95- `database` - Database patterns96- `authentication` - Auth approaches97- `api` - API design patterns98- `frontend` - Frontend patterns99- `performance` - Performance optimizations100101## Outcome Flags102103- `--success` - Pattern that worked well (positive outcome)104- `--failed` - Pattern that caused problems (anti-pattern)105106If neither flag is provided, the memory is stored as neutral (informational).107108## Workflow109110### 1. Parse Input111112```113Check for --success flag → outcome: success114Check for --failed flag → outcome: failed115Check for --category <category> flag116Check for --agent <agent-id> flag → agent_id: "ork:{agent-id}"117Check for --global flag → use global user_id118Extract the text to remember119If no category specified, auto-detect from content120```121122### 2. Auto-Detect Category123124| Keywords | Category |125|----------|----------|126| chose, decided, selected | decision |127| architecture, design, system | architecture |128| pattern, convention, style | pattern |129| blocked, issue, bug, workaround | blocker |130| must, cannot, required, constraint | constraint |131| pagination, cursor, offset, page | pagination |132| database, sql, postgres, query | database |133| auth, jwt, oauth, token, session | authentication |134| api, endpoint, rest, graphql | api |135| react, component, frontend, ui | frontend |136| performance, slow, fast, cache | performance |137138### 3. Extract Lesson (for anti-patterns)139140If outcome is "failed", look for:141- "should have", "instead use", "better to"142- If not found, prompt user: "What should be done instead?"143144### 4-6. Extract Entities and Create Graph145146Extract entities (Technology, Agent, Pattern, Project, AntiPattern) from the text, detect relationship patterns ("X uses Y", "chose X over Y", etc.), then create entities and relations in the knowledge graph.147148### 7. Confirm Type + Scope (AskUserQuestion — M118 #1466)149150Auto-classification is best-effort. Before writing, ask the user to confirm both the memory type and the persistence scope. Pre-select the auto-detected type as the default option when the classifier is confident (≥0.9):151152```python153# Skip when the invocation already specifies type and scope:154# remember --type=preference --global → skip, use those values155# remember --session → skip, no persistence156#157# Otherwise, ask both:158AskUserQuestion(questions=[159 {"question": "What type of memory?",160 "header": "Type",161 "options": [162 {"label": "Preference", "description": "How I like to work (style, format, tooling)"},163 {"label": "Project fact", "description": "State of THIS codebase (decisions, constraints)"},164 {"label": "Reference", "description": "External system pointer (URL, doc, dashboard)"},165 {"label": "Feedback", "description": "Correction to future behavior — applied as a rule"}166 ]},167 {"question": "Apply to?",168 "header": "Scope",169 "options": [170 {"label": "This project (default)", "description": "Scoped to .claude/projects/<this-project>/memory/"},171 {"label": "All projects (global)", "description": "User-level memory at ~/.claude/memory/"},172 {"label": "This session only", "description": "Print to context but don't persist"}173 ]}174])175```176177**Default selection rules:**178- If auto-detected category maps to one of the 4 type options with confidence ≥0.9, that option is pre-selected (the user can still override).179- "This project" is always the scope default.180- "This session only" returns immediately without writing — useful when the user wants to surface a fact for the conversation but not commit it.181182**Global memory writes** route to `~/.claude/memory/<filename>.md` instead of the project-local memory directory. The MEMORY.md index is updated in whichever scope was selected (project- or user-level).183184Load entity extraction rules, type assignment, relationship patterns, and graph creation examples: `Read("references/graph-operations.md")`185186### 7. Confirm Storage187188Display confirmation using the appropriate template (success, anti-pattern, or neutral) showing created entities, relations, and graph stats.189190Load output templates and examples: `Read("references/confirmation-templates.md")`191192## File-Based Memory Updates193194When updating `.claude/memory/MEMORY.md` or project memory files:195- **PREFER Edit over Write** to preserve existing content and avoid overwriting196- Use stable anchor lines: `## Recent Decisions`, `## Patterns`, `## Preferences`197- See the `memory` skill's "Permission-Free File Operations" section for the full Edit pattern198- This applies to the calling agent's file operations, not to the knowledge graph operations above199200---201202## References203204Load on demand with `Read("references/<file>")`:205206| File | Content |207|------|---------|208| `category-detection.md` | Auto-detection rules for categorizing memories (priority order) |209| `graph-operations.md` | Entity extraction, type assignment, relationship patterns, graph creation |210| `confirmation-templates.md` | Output templates (success, anti-pattern, neutral) and usage examples |211212---213214## Related Skills215- `ork:memory` - Search, load, sync, visualize (read-side operations)216217## Error Handling218219- Knowledge graph unavailable → show configuration instructions220- Empty text → ask user for content; text >2000 chars → truncate with notice221- Both --success and --failed → ask user to clarify222- Entity extraction fails → create generic Decision entity; relation fails → create entities first, retry