# Recall Usage Guide
## Three Ways to Use Recall
| Method | Who Controls | When It Runs |
|--------|--------------|--------------|
| **MCP Tools** | Claude decides | When Claude thinks it's relevant |
| **Hooks** | Automatic | Session start/end, tool use, etc. |
| **Slash Commands** | You decide | When you invoke them |
---
## Slash Commands (Explicit Control)
| Command | Purpose |
|---------|---------|
| `/remember <text>` | Store a memory you want kept |
| `/recall <query>` | Search your memories |
| `/memories` | List all stored memories |
| `/forget <query>` | Delete memories |
**Example:**
```
/remember always use pytest, never unittest
/recall testing preferences
/memories
/forget outdated preference
```
---
## Hooks (Automatic)
Recall provides **15 hooks** that run automatically:
| Category | Hooks | What They Do |
|----------|-------|--------------|
| **Session Lifecycle** | session-start, context, capture, stop | Track sessions, load/save memories |
| **Tool Interception** | prompt, precontext, security, permissions, track | Inject context, validate commands |
| **Specialized** | compact, monitor, notify, subagent | Preserve context, health checks |
| **Background** | daemon, daemon-ctl | Fast IPC operations (<10ms) |
You don't invoke these - they run automatically based on Claude Code events.
See [hooks-setup.md](./hooks-setup.md) for full configuration details.
---
## MCP Tools (Claude's Choice)
Claude can call these when it thinks they're useful:
### Core Memory Tools
| Tool | Purpose |
|------|---------|
| `memory_store_tool` | Store a memory with semantic indexing |
| `memory_recall_tool` | Search memories by semantic similarity |
| `memory_relate_tool` | Link memories together (supersedes, contradicts, etc.) |
| `memory_context_tool` | Get formatted context for injection |
| `memory_forget_tool` | Delete memories (golden rules protected) |
| `memory_list_tool` | List memories with filtering |
| `memory_count_tool` | Count memories by namespace/type |
### Validation Tools (TRY-LEARN Cycle)
| Tool | Purpose |
|------|---------|
| `memory_apply_tool` | Record that a memory is being applied (TRY phase) |
| `memory_outcome_tool` | Record the result of applying a memory (LEARN phase) |
| `memory_validate_tool` | Adjust confidence based on success/failure |
| `validation_history_tool` | View validation event history |
### System Tools
| Tool | Purpose |
|------|---------|
| `daemon_status_tool` | Check if the recall daemon is running |
| `file_activity_add` | Record file activity events |
| `file_activity_recent` | Get recently accessed files |
**When Claude uses them:** If you mention preferences, make decisions, or ask about past context - Claude may proactively store/recall.
---
## Validation Loop (TRY-LEARN)
Recall builds confidence in memories through practical use:
```
TRY → BREAK → ANALYZE → LEARN
↑ ↓
└────────────────────────┘
```
### How It Works
1. **TRY** - Apply a memory using `memory_apply_tool`
```javascript
await recall.memory_apply_tool({
memory_id: "mem_123",
context: "Using dark mode preference for UI settings"
});
```
2. **BREAK** - Memory application either succeeds or fails
3. **ANALYZE** - Evaluate what happened
4. **LEARN** - Update confidence using `memory_outcome_tool`
```javascript
await recall.memory_outcome_tool({
memory_id: "mem_123",
success: true, // or false
outcome: "User accepted the setting"
});
```
### Confidence Changes
| Outcome | Confidence Change |
|---------|-------------------|
| Success | +0.1 (max 1.0) |
| Failure | -0.15 (min 0.0) |
Memories at confidence ≥ 0.9 are automatically promoted to **golden rules**.
---
## Golden Rules
Golden rules are high-confidence memories that represent validated, constitutional principles:
| Aspect | Behavior |
|--------|----------|
| **Auto-promotion** | Memories with confidence ≥ 0.9 are automatically promoted |
| **Eligible types** | Only `preference`, `decision`, and `pattern` can be promoted |
| **Protected** | Cannot be deleted unless `force=True` is specified |
| **Always visible** | Appear in context regardless of token budget or recency |
| **Original type** | Stored in `metadata.promoted_from` |
**Example golden rule:**
```
[GOLDEN RULE] You MUST use pytest for all tests. You MUST NOT use unittest.
```
---
## Memory Types
| Type | Example | Description |
|------|---------|-------------|
| `preference` | "Use 2-space indent", "Prefer dark mode" | User preferences or settings |
| `decision` | "Chose FastAPI for backend", "Using PostgreSQL" | Design or implementation decisions |
| `pattern` | "Always run tests before commit" | Recognized patterns or recurring behaviors |
| `session` | Temporary context from conversations | Session-related information |
| `file_context` | File activity tracking | What files were touched |
| `golden_rule` | High-confidence validated principles | Constitutional rules (promoted from other types) |
---
## Namespaces
| Namespace | Scope |
|-----------|-------|
| `global` | Applies everywhere |
| `project:{name}` | Scoped to specific project |
Memories are auto-scoped based on your working directory.
**Example:**
- Working in `/Users/me/projects/myapp` → `project:myapp`
- Generic preferences → `global`
---
## When to Use What
| Situation | Use |
|-----------|-----|
| "I want this remembered for sure" | `/remember` |
| "What do I have stored?" | `/memories` |
| "Find my preferences on X" | `/recall X` |
| "Delete old/wrong memories" | `/forget` |
| "Just working normally" | Let hooks + MCP handle it |
| "Check if daemon is running" | `daemon_status_tool` |
| "See if a memory is working" | `validation_history_tool` |
---
## RFC 2119 Requirement Language
Memories follow [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) semantics for requirement keywords:
| Keyword | Meaning | Use For |
|---------|---------|---------|
| **MUST** / **REQUIRED** | Absolute requirement | Hard rules that cannot be ignored |
| **MUST NOT** / **SHALL NOT** | Absolute prohibition | Actions that are never allowed |
| **SHOULD** / **RECOMMENDED** | Strong suggestion | Preferences with valid escape hatches |
| **SHOULD NOT** | Strong discouragement | Generally avoid unless justified |
| **MAY** / **OPTIONAL** | Truly optional | Nice-to-haves |
### Writing Effective Memories
**Weak (avoid):**
```
User prefers pytest over unittest
```
**Strong (preferred):**
```
You MUST use pytest for all tests. You MUST NOT use unittest.
```
Soft language ("prefers", "wants", "likes") gets rationalized and ignored under time pressure. RFC 2119 keywords have defined semantics that are harder to bypass.
---
## See Also
- [Hooks Setup Guide](./hooks-setup.md) - Configure Claude Code hooks
- [Main README](../README.md) - General Recall documentation
