1  # Memory Tool
  2  
  3  Persistent knowledge storage across conversations. Store facts, preferences, context, and decisions so they survive beyond the current session.
  4  
  5  ## Memory Tiers
  6  
  7  | Tier | Scope | Lifetime | Use For |
  8  |------|-------|----------|---------|
  9  | **Working** | Current session | Session duration | Scratch notes, intermediate results, task state |
 10  | **Durable** | Cross-session | Permanent until deleted | User preferences, project facts, learned patterns |
 11  | **Archive** | Cross-session | Permanent, lower priority | Completed task summaries, historical context |
 12  
 13  ## Actions
 14  
 15  | Action | Description | Key Parameters |
 16  |--------|-------------|----------------|
 17  | `store` | Save a new memory | `title`, `value`, `category` |
 18  | `search` | Find memories by query | `query`, `scope` (optional) |
 19  | `get` | Retrieve a specific memory | `id` or `key` |
 20  | `update` | Modify an existing memory | `id`, `value` (and/or `title`, `category`) |
 21  
 22  ## Store
 23  
 24  ```json
 25  {
 26    "action": "store",
 27    "title": "User prefers dark mode",
 28    "value": "The user explicitly asked for dark mode in all UI components. Use dark backgrounds (#1a1a2e) with light text (#e0e0e0).",
 29    "category": "preference"
 30  }
 31  ```
 32  
 33  ### Categories
 34  
 35  | Category | When to Use |
 36  |----------|------------|
 37  | `preference` | User likes, dislikes, style choices |
 38  | `fact` | Verified information about user, project, or domain |
 39  | `decision` | Architecture decisions, design choices with rationale |
 40  | `context` | Background info that helps future conversations |
 41  | `note` | General observations, reminders |
 42  | `identity` | Agent's learned personality traits, communication style |
 43  
 44  ## Search
 45  
 46  ```json
 47  { "action": "search", "query": "database schema preferences" }
 48  ```
 49  
 50  Returns ranked results with relevance scores. Supports semantic-style matching (expanded query terms).
 51  
 52  ### Scope Filtering
 53  
 54  ```json
 55  { "action": "search", "query": "API keys", "scope": "agent" }
 56  ```
 57  
 58  | Scope | What It Searches |
 59  |-------|-----------------|
 60  | `auto` | Smart default: session + agent + global (recommended) |
 61  | `session` | Current session only |
 62  | `agent` | Current agent's memories |
 63  | `project` | Current project's memories |
 64  | `global` | Shared across all agents |
 65  | `all` | Everything |
 66  
 67  ## Update
 68  
 69  ```json
 70  { "action": "update", "id": "mem_abc123", "value": "Updated: user now prefers system theme over dark mode" }
 71  ```
 72  
 73  Use `update` when information changes. Avoids creating duplicate memories.
 74  
 75  ## When to Remember
 76  
 77  **Do remember:**
 78  - User-stated preferences ("I prefer TypeScript", "always use tabs")
 79  - Corrections ("actually, the API endpoint is /v2/...")
 80  - Project-specific facts (tech stack, coding conventions, team structure)
 81  - Important decisions and their rationale
 82  
 83  **Do not remember:**
 84  - Ephemeral task details (file paths being edited right now)
 85  - Information already in the codebase (README, config files)
 86  - Trivial conversational context
 87  - Sensitive data (passwords, tokens, private keys)
 88  
 89  ## When to Forget
 90  
 91  Use `update` to revise outdated memories rather than storing contradictory ones. If a memory is no longer relevant, update its value to reflect the current state.
 92  
 93  ## Memory in Practice
 94  
 95  1. **Start of session**: Relevant memories are automatically injected into context based on the current agent, project, and conversation topic.
 96  2. **During conversation**: Store new insights as they emerge. Search when you need to recall something.
 97  3. **End of significant interaction**: Store a summary of decisions made, preferences learned, or context that would help next time.
 98  
 99  ## Tips
100  
101  - Write memories in the third person for clarity: "The user prefers..." not "You prefer..."
102  - Include enough context in the `value` that the memory is useful standalone
103  - Use descriptive `title` fields -- they're used for search ranking
104  - Prefer `category: "decision"` for architectural choices so they can be filtered later