6 Tools

Memory Tools

Store, search, and manage memories. These tools form the core of HyperSpark Memory, enabling persistent context across conversations.

remember
Store new memories from conversation messages

Parameters

NameTypeRequiredDescription
messagesarrayRequiredArray of conversation messages with role (user/assistant) and content
userIdstringOptionalUser identifier (uses authenticated user if not provided)
contextstringOptionalAdditional context about this conversation

Example Usage

{
  "messages": [
    { "role": "user", "content": "I prefer to work in the mornings" },
    { "role": "assistant", "content": "Got it! I'll remember you prefer morning work sessions." }
  ],
  "context": "Discussing work schedule preferences"
}

Example Response

Stored 1 memories
IDs: mem_1735638400000_abc123

Tips & Best Practices

  • Check with recall first to avoid storing duplicates
  • Don't store trivial or temporary information
  • Include context for better categorization
  • The system automatically deduplicates similar memories
recall
Semantic search for relevant memories using meaning-based matching

Parameters

NameTypeRequiredDescription
querystringRequiredNatural language query - richer queries yield better matches
topKnumberOptionalResults to return (default: 30, max: 100)
userIdstringOptionalUser identifier (uses authenticated user if not provided)
filters.ringsarrayOptionalFilter by memory type: episodic, semantic, procedural
filters.domainsarrayOptionalFilter by life domain: work, finance, projects, goals, etc.
filters.minImportancenumberOptionalMinimum importance score (1-10)
filters.decisionsOnlybooleanOptionalOnly return decision memories
filters.decisionOutcomestringOptionalFilter by outcome: pending, successful, failed, unknown
filters.precedentsOnlybooleanOptionalOnly return precedent-setting decisions
filters.exceptionsOnlybooleanOptionalOnly return policy exceptions
filters.decisionSincestringOptionalTime filter: 7d, 30d, 90d, quarter, year
filters.decisionActionstringOptionalFilter by specific decision action (e.g., "approved_discount", "denied_refund")
filters.policyAppliedstringOptionalFilter by policy identifier (e.g., "refund_policy_v2")
orgWidebooleanOptionalSearch across all users in org (admin only)

Example Usage

{
  "query": "user's job, company, and responsibilities",
  "topK": 10,
  "filters": {
    "domains": ["work"],
    "minImportance": 5
  }
}

Example Response

Found 3 memories (45ms):

1. [mem_abc123] [semantic/work] User works as a Senior Engineer at TechCorp
   Score: 92% | Created: 12/30/2024

2. [mem_def456] [episodic/work] Mentioned leading the platform team
   Score: 85% | Created: 12/28/2024

3. [mem_ghi789] [semantic/work] Prefers async communication
   Score: 78% | Created: 12/25/2024

Tips & Best Practices

  • Use descriptive queries: 'user's food preferences and dietary restrictions' beats 'food'
  • Memory IDs [mem_xxx] can be used with log_decision.memoriesConsidered
  • Results are scored by: relevance (60%), importance (25%), recency (15%)
  • For recent memories by time, use recall_recent instead (faster)
recall_recent
Get recent memories sorted by creation time (newest first)

Parameters

NameTypeRequiredDescription
limitnumberOptionalNumber of memories to return (default: 30, max: 500)
sincestringOptionalTime filter: 24h, 7d, 30d, or 90d
userIdstringOptionalUser identifier (uses authenticated user if not provided)
filters.ringsarrayOptionalFilter by memory type
filters.domainsarrayOptionalFilter by life domain
orgWidebooleanOptionalSearch across all users in org (admin only)

Example Usage

{
  "limit": 10,
  "since": "7d",
  "filters": {
    "domains": ["work", "projects"]
  }
}

Example Response

10 recent memories (12ms):

1. [mem_abc123] [episodic/work] Completed code review for auth module
   Created: 12/31/2024, 2:30 PM | Importance: 7/10

2. [mem_def456] [episodic/projects] Started new feature branch for payments
   Created: 12/31/2024, 10:15 AM | Importance: 6/10

Tips & Best Practices

  • Faster than recall - no embedding computation needed
  • Use for chronological browsing, use recall for topic searches
  • Great for understanding recent context before diving deeper
get_context
Get a formatted context block with the user's most relevant information

Parameters

NameTypeRequiredDescription
maxTokensnumberOptionalMaximum tokens for context (default: 2000)
focusarrayOptionalLife domains to focus on: work, finance, projects, goals, relationships, lifestyle, health, interests
userIdstringOptionalUser identifier (uses authenticated user if not provided)
orgWidebooleanOptionalGet context across all users in org (admin only)

Example Usage

{
  "maxTokens": 1500,
  "focus": ["work", "projects"]
}

Example Response

## User Context

### Identity & Background
- Senior Software Engineer at TechCorp (3 years)
- Leads the platform infrastructure team
- Based in San Francisco, PST timezone

### Preferences & Working Style
- Prefers async communication
- Morning person - most productive 6-10 AM
- Uses vim, dark mode, mechanical keyboard

### Current Focus
- Q1 platform migration project
- Mentoring two junior engineers
- Learning Rust on the side

---
_23 memories_

Tips & Best Practices

  • Call this FIRST in every conversation before diving into work
  • Use focus parameter to narrow context for specific domains
  • Context includes identity, preferences, recent activity, and procedural knowledge
  • Don't proceed without understanding user context
forget_preview
Preview what memories will be affected by a forget request

Parameters

NameTypeRequiredDescription
querystringRequiredNatural language description of what to forget (e.g., "my old address")
topKnumberOptionalMaximum memories to consider (default: 50)
userIdstringOptionalUser identifier (uses authenticated user if not provided)
orgWidebooleanOptionalSearch across all users in org (admin only)

Example Usage

{
  "query": "my old home address on Oak Street"
}

Example Response

## Forget Preview

**Summary:** Will delete 2 memories containing the Oak Street address. 1 memory will be rewritten to preserve work context while removing the address.

### Will FORGET (2)
1. My home address is 123 Oak Street, Apt 4B
   _Directly contains the address to forget_

2. Lived on Oak Street for 3 years
   _Contains reference to the address_

### Will REWRITE (1)
1. **Before:** Commuted from Oak Street to downtown TechCorp office
   **After:** Commuted to downtown TechCorp office
   _Preserves work commute info while removing address_

---
**Plan ID:** fp_abc123def456

Use `forget_confirm` with this plan ID to execute.

Tips & Best Practices

  • AI decides: FORGET (delete), REWRITE (partial removal), or KEEP
  • User MUST review the plan before confirming
  • Plan expires after 24 hours
  • REWRITE preserves valuable context while removing sensitive info
forget_confirm
Execute a reviewed forget plan

Parameters

NameTypeRequiredDescription
planIdstringRequiredThe plan ID from forget_preview response

Example Usage

{
  "planId": "fp_abc123def456"
}

Example Response

## Forget Plan Executed

- Forgotten: 2
- Rewritten: 1
- Kept: 5

Tips & Best Practices

  • This action is PERMANENT
  • Verify user consent before executing
  • Plan must be used within 24 hours of creation
  • Cancelled or expired plans require a new preview