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
When to Use
- At the END of a conversation, after the user's goals are accomplished
- When the user explicitly shares personal information or preferences
- After significant decisions, milestones, or conclusions are reached
- When you learn something valuable for future interactions
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| messages | array | Required | Array of conversation messages with role (user/assistant) and content |
| userId | string | Optional | User identifier (uses authenticated user if not provided) |
| context | string | Optional | Additional 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_abc123Tips & 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
When to Use
- User asks "What do I...", "What's my...", "Do I have..."
- User references past conversations: "Remember when...", "Last time..."
- Before giving personalized recommendations
- When uncertain about user preferences - check rather than guess
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Required | Natural language query - richer queries yield better matches |
| topK | number | Optional | Results to return (default: 30, max: 100) |
| userId | string | Optional | User identifier (uses authenticated user if not provided) |
| filters.rings | array | Optional | Filter by memory type: episodic, semantic, procedural |
| filters.domains | array | Optional | Filter by life domain: work, finance, projects, goals, etc. |
| filters.minImportance | number | Optional | Minimum importance score (1-10) |
| filters.decisionsOnly | boolean | Optional | Only return decision memories |
| filters.decisionOutcome | string | Optional | Filter by outcome: pending, successful, failed, unknown |
| filters.precedentsOnly | boolean | Optional | Only return precedent-setting decisions |
| filters.exceptionsOnly | boolean | Optional | Only return policy exceptions |
| filters.decisionSince | string | Optional | Time filter: 7d, 30d, 90d, quarter, year |
| filters.decisionAction | string | Optional | Filter by specific decision action (e.g., "approved_discount", "denied_refund") |
| filters.policyApplied | string | Optional | Filter by policy identifier (e.g., "refund_policy_v2") |
| orgWide | boolean | Optional | Search 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/2024Tips & 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)
When to Use
- User asks "What have we discussed recently?"
- "Catch me up" or "What's been happening?"
- When you need temporal context before a semantic search
- Checking what was just discussed
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | number | Optional | Number of memories to return (default: 30, max: 500) |
| since | string | Optional | Time filter: 24h, 7d, 30d, or 90d |
| userId | string | Optional | User identifier (uses authenticated user if not provided) |
| filters.rings | array | Optional | Filter by memory type |
| filters.domains | array | Optional | Filter by life domain |
| orgWide | boolean | Optional | Search 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/10Tips & 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
When to Use
- FIRST thing to call in every new conversation
- When you need a comprehensive overview of the user
- Before making personalized recommendations
- Understanding user identity and preferences
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| maxTokens | number | Optional | Maximum tokens for context (default: 2000) |
| focus | array | Optional | Life domains to focus on: work, finance, projects, goals, relationships, lifestyle, health, interests |
| userId | string | Optional | User identifier (uses authenticated user if not provided) |
| orgWide | boolean | Optional | Get 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
When to Use
- ALWAYS use before forgetting memories
- When user asks to forget something
- Reviewing what will be affected before deletion
- User privacy requests
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Required | Natural language description of what to forget (e.g., "my old address") |
| topK | number | Optional | Maximum memories to consider (default: 50) |
| userId | string | Optional | User identifier (uses authenticated user if not provided) |
| orgWide | boolean | Optional | Search 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
When to Use
- ONLY after user reviews forget_preview results
- ONLY when user explicitly confirms
- Executing approved privacy deletions
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| planId | string | Required | The plan ID from forget_preview response |
Example Usage
{
"planId": "fp_abc123def456"
}Example Response
## Forget Plan Executed
- Forgotten: 2
- Rewritten: 1
- Kept: 5Tips & 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