Skip to content

Memory Operations

Jump to bottom
Zhafron Kautsar edited this page Jan 12, 2026 · 3 revisions

Memory Operations

Complete guide to using the memory tool for storing and retrieving information.

Memory Tool Overview

The memory tool provides 9 modes for managing persistent memory:

  • add - Store new memory
  • search - Find similar memories
  • profile - View user profile
  • list - List recent memories
  • forget - Delete specific memory
  • help - Display usage guide
  • capture-now - Trigger manual capture
  • auto-capture-toggle - Enable/disable auto-capture
  • auto-capture-stats - View capture statistics

Add Memory

Store new information with scope and metadata.

⚠️ Deprecation Notice (v2.2+): User-scoped add is deprecated. Use the User Profile System instead, which automatically learns from your prompts.

Basic Usage

Project-scoped (still supported):

memory({
  mode: "add",
  content: "This project uses React 18 with Vite",
  
})

User-scoped (deprecated):

// ❌ No longer works in v2.2+
memory({
  mode: "add",
  content: "User prefers TypeScript over JavaScript",
  
})
// Returns error: "User-scoped memories are deprecated"

With Type

memory({
  mode: "add",
  content: "This project uses React 18 with Vite",
  ,
  type: "architecture"
})

Parameters

  • mode: "add" (required)
  • content: Memory content (required)
  • scope: "project" only (required) - "user" deprecated in v2.2+
  • type: Memory type (optional)

Memory Types

Common types (flexible string):

  • preference - User preferences
  • architecture - System design decisions
  • workflow - Process and workflow patterns
  • bug-fix - Bug solutions and fixes
  • configuration - Config settings
  • pattern - Code patterns and conventions
  • request - User requests and requirements
  • context - General context information

Examples

Project architecture:

memory({
  mode: "add",
  content: "API uses REST with JWT authentication",
  ,
  type: "architecture"
})

Bug fix:

memory({
  mode: "add",
  content: "Fixed memory leak by clearing interval in useEffect cleanup",
  ,
  type: "bug-fix"
})

User preferences (use profile system instead):

For user preferences, the system now automatically learns from your prompts. See User Profile System for details.

Search Memory

Find memories using vector similarity search.

Basic Usage

memory({
  mode: "search",
  query: "What are my coding preferences?",
  
})

Cross-Scope Search

Search both scopes:

memory({
  mode: "search",
  query: "authentication implementation"
})

Parameters

  • mode: "search" (required)
  • query: Search query (required)
  • scope: "user", "project", or omit for both (optional)

Search Behavior

  • Uses vector similarity (cosine distance)
  • Returns most relevant memories first
  • Respects similarityThreshold from config
  • Limited by maxMemories and maxProjectMemories

Examples

Find coding style:

memory({
  mode: "search",
  query: "code formatting preferences",
  
})

Find project tech stack:

memory({
  mode: "search",
  query: "what technologies does this project use",
  
})

View Profile

Display structured user profile with preferences, patterns, workflows, and skill assessment.

🆕 New in v2.2: Profile structure completely redesigned. See User Profile System for full details.

Basic Usage

memory({ mode: "profile" })

Profile Structure (v2.2+)

The profile includes:

Preferences (with confidence scores):

  • Code style preferences
  • Communication preferences
  • Tool preferences
  • Evidence-backed with example prompts

Patterns (with frequency tracking):

  • Recurring topics
  • Problem domains
  • Technical interests

Workflows:

  • Development sequences
  • Habits and processes
  • Learning style

Skill Level:

  • Overall assessment (beginner/intermediate/advanced)
  • Per-domain assessments

Metadata:

  • Version number
  • Last analyzed timestamp
  • Total prompts analyzed

Parameters

  • mode: "profile" (required)

Example Output (v2.2+)

{
  "success": true,
  "profile": {
    "preferences": [
      {
        "category": "Code Style",
        "description": "Prefers TypeScript over JavaScript",
        "confidence": 0.9,
        "evidence": ["Can we use TypeScript?", "Add TS types here"],
        "lastUpdated": 1736668800000
      }
    ],
    "patterns": [
      {
        "category": "Technical Domain",
        "description": "Frequently works on authentication",
        "frequency": 15,
        "lastSeen": 1736668800000
      }
    ],
    "workflows": [
      {
        "description": "Usually asks for tests after implementation",
        "steps": ["Implement feature", "Request tests", "Review coverage"],
        "frequency": 10
      }
    ],
    "skillLevel": {
      "overall": "intermediate",
      "domains": {
        "typescript": "advanced",
        "docker": "beginner"
      }
    },
    "version": 5,
    "lastAnalyzed": "2026-01-12T10:30:00Z",
    "totalPromptsAnalyzed": 50
  }
}

Migration from v2.1

Old structure (v2.1 and earlier):

{
  "profile": {
    "static": ["fact1", "fact2"],
    "dynamic": ["fact3", "fact4"]
  }
}

New structure (v2.2+):

{
  "profile": {
    "preferences": [{...}],
    "patterns": [{...}],
    "workflows": [{...}],
    "skillLevel": {...}
  }
}

See User Profile System for complete migration guide.

List Memories

Retrieve recent memories by scope.

Basic Usage

memory({
  mode: "list",
  ,
  limit: 10
})

Parameters

  • mode: "list" (required)
  • scope: "user" or "project" (required)
  • limit: Number of memories (optional, default: 10)

Examples

List recent user memories:

memory({
  mode: "list",
  ,
  limit: 5
})

List all project memories:

memory({
  mode: "list",
  ,
  limit: 100
})

Forget Memory

Delete a specific memory by ID.

Basic Usage

memory({
  mode: "forget",
  memoryId: "mem_abc123"
})

Parameters

  • mode: "forget" (required)
  • memoryId: Memory ID (required)

Finding Memory IDs

Get memory IDs from:

  • List operation results
  • Search operation results
  • Web interface

Example

memory({ mode: "list", limit: 5 })

Output includes IDs:

1. [mem_abc123] User prefers TypeScript
2. [mem_def456] Uses React for frontend

Delete specific memory:

memory({ mode: "forget", memoryId: "mem_abc123" })

Help

Display usage guide and available modes.

Basic Usage

memory({ mode: "help" })

Shows:

  • Available modes
  • Parameter descriptions
  • Usage examples
  • Configuration tips

Capture Now

Manually trigger memory capture from recent conversation.

Basic Usage

memory({ mode: "capture-now" })

Requirements

  • Auto-capture must be configured
  • API credentials must be set
  • Recent conversation history available

Behavior

  • Analyzes recent messages
  • Extracts important information
  • Stores memories with appropriate scope
  • Returns capture results

Auto-Capture Toggle

Enable or disable automatic memory capture.

Basic Usage

memory({ mode: "auto-capture-toggle" })

Behavior

  • Toggles current state (on/off)
  • Returns new state
  • Persists across sessions

Example

memory({ mode: "auto-capture-toggle" })

Output:

Auto-capture is now: enabled

Auto-Capture Stats

View statistics about automatic memory capture.

Basic Usage

memory({ mode: "auto-capture-stats" })

Statistics Included

  • Total captures performed
  • Total memories created
  • Average memories per capture
  • Last capture timestamp
  • Token counts

Example Output

Auto-Capture Statistics:
- Total captures: 15
- Total memories: 127
- Average per capture: 8.5
- Last capture: 2026-01-11 10:30:00
- Total tokens processed: 150,000

Best Practices

Content Guidelines

Be Specific:

memory({
  mode: "add",
  content: "User prefers 2-space indentation for TypeScript files",
  
})

Include Context:

memory({
  mode: "add",
  content: "API rate limit is 100 requests per minute, implemented using Redis",
  
})

Avoid Redundancy:

Check existing memories before adding:

memory({ mode: "search", query: "indentation preference" })

Scope Selection

User Scope - For cross-project information:

  • Personal preferences
  • General knowledge
  • Tool preferences
  • Communication style

Project Scope - For project-specific information:

  • Architecture decisions
  • Technology stack
  • Code conventions
  • Bug fixes
  • Feature implementations

Search Tips

Use Natural Language:

memory({
  mode: "search",
  query: "How should I format code in this project?"
})

Be Specific:

memory({
  mode: "search",
  query: "React component testing strategy"
})

Adjust Threshold:

If getting too few results, lower similarity threshold in config:

{
  "similarityThreshold": 0.5
}

Memory Maintenance

Regular Cleanup:

Use web interface or API to remove outdated memories.

Deduplication:

Run deduplication periodically to remove similar duplicates.

Review Profile:

Check profile regularly to ensure accurate representation:

memory({ mode: "profile" })

Advanced Usage

Batch Operations

Add multiple memories:

const memories = [
  { content: "Prefers functional components" },
  { content: "Uses React hooks exclusively" },
  { content: "Avoids class components" }
]

memories.forEach(mem => memory({ mode: "add", ...mem }))

Conditional Storage

Store only if not exists:

const results = memory({
  mode: "search",
  query: "TypeScript preference",
  
})

if (results.length === 0) {
  memory({
    mode: "add",
    content: "Prefers TypeScript over JavaScript",
    
  })
}

Memory Migration

Move memories between scopes:

const userMems = memory({ mode: "list" })

userMems.forEach(mem => {
  if (mem.content.includes("project-specific")) {
    memory({
      mode: "add",
      content: mem.content,
      
    })
    memory({ mode: "forget", memoryId: mem.id })
  }
})

Error Handling

Common Errors

Missing Required Parameters:

memory({ mode: "add" })

Error: content and scope are required

Invalid Scope:

memory({ mode: "add", content: "test", scope: "invalid" })

Error: scope must be 'user' or 'project'

Memory Not Found:

memory({ mode: "forget", memoryId: "invalid_id" })

Error: Memory not found

Validation

The tool validates:

  • Required parameters
  • Parameter types
  • Scope values
  • Memory ID format

Next Steps

Clone this wiki locally