Core Concepts

Understand the key concepts in the Tensorheart Memory API.

Memories

A memory is a piece of information you want your AI to remember.

{
  "id": "mem_abc123",
  "text": "User prefers Python for data analysis",
  "metadata": {
    "category": "preference",
    "confidence": 0.95
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Memory Components

Field	Description
text	The memory content (required)
metadata	Key-value pairs for organization
id	Unique identifier (auto-generated or custom)
space_id	Optional namespace for organization
entities	Extracted entities (people, orgs, skills, etc.)

Smart Updates

Smart updates automatically handle conflicting information when adding memories.

Existing: "Alice has 5 years of experience"
    +
New: "Alice has 6 years of experience"
    ↓
Smart resolution: UPDATE (refinement detected)
    ↓
Result: Old version preserved, new version is current

Conflict Types

Type	Description	Action
Contradiction	New info contradicts existing	Updates the memory
Refinement	New info improves existing	Updates the memory
Addition	New info is complementary	Adds new memory
Duplicate	Already captured	No action (returns existing)

Enable smart updates by setting smart: true when creating memories.

Temporal Versioning

Temporal versioning maintains a complete history of memory changes.

Jan 2024: "Alice has 5 years of experience"
    ↓ (superseded)
Jun 2024: "Alice has 5.5 years of experience"
    ↓ (superseded)
Dec 2024: "Alice has 6 years of experience" [current]

Benefits

• Audit trails: See what was known at any point in time
• Point-in-time queries: Query memories as of a specific date
• Change tracking: Understand how information evolved

Use as_of in queries to retrieve memories as they existed at a specific timestamp.

Entity Extraction

Entity extraction identifies structured data in your memories.

{
  "text": "Alice works at Acme Corp as a Python engineer",
  "entities": {
    "PERSON": ["Alice"],
    "ORG": ["Acme Corp"],
    "SKILL": ["Python"]
  }
}

Entity Types

Type	Examples
PERSON	Alice, John Smith
ORG	Google, Acme Corp
LOCATION	San Francisco, Japan
SKILL	Python, Machine Learning
PRODUCT	iPhone, AWS

Enable extraction by setting extract_entities: true when creating memories.

Memory Spaces

Spaces are namespaces that organize memories into isolated groups.

├── work/
│   ├── "User manages the API team"
│   └── "Project deadline is March 15"
├── personal/
│   ├── "User likes hiking"
│   └── "Favorite coffee: espresso"

Use spaces to separate memories by user, project, or topic.

Retrieval

Retrieval returns memories that best match the context you provide.

Query: "What programming language does the user prefer?"
    ↓
Intelligent matching
    ↓
Returns: "User prefers Python for data analysis" (relevance_score: 0.92)

Relevance Scores

Each returned memory includes a relevance score from 0 to 1:

• 0.9-1.0: Highly relevant
• 0.7-0.9: Relevant
• 0.5-0.7: Possibly relevant
• < 0.5: Likely not relevant

Query Parameters

Control retrieval behavior with these options:

• search_depth (0-1): Controls search thoroughness
  • 0.0-0.3: Fast searches, ideal for large datasets
  • 0.5 (default): Balanced accuracy and speed
  • 0.7-1.0: Exhaustive searches for critical queries
• query_rewrite: Expands your query for better recall
• hybrid_search: Combines keyword and semantic matching
• temporal_boost: Prioritizes recent memories
• relevance_threshold: Minimum score for returned memories (0-1)

Answer Generation

The API can generate answers based on retrieved memories:

Question: "What should I use for the user's data project?"
    ↓
Retrieve relevant memories
    ↓
Generate answer: "Based on the user's preferences,
                  Python would be ideal for their data project."

Organizations

An organization is your account. All data is isolated per organization.

• Each org has its own memories
• Multiple API keys per org
• Separate billing and usage

API Keys

API keys authenticate requests and define permissions.

• mem_live_... - Production (billed)
• mem_test_... - Testing (free)

Keys have scopes: read, write, delete, admin

Rate Limits

Requests are limited per plan:

Plan	Requests/min
Free	10
Starter	60
Professional	300

Metadata

Use metadata to organize and filter memories:

{
  "text": "User completed onboarding",
  "metadata": {
    "category": "event",
    "timestamp": "2024-01-15",
    "importance": "high"
  }
}

Best practices:

• Use consistent key names
• Keep values simple (strings, numbers, booleans)
• Don't store sensitive data in metadata

Transparent Proxy

The Transparent Proxy adds memory to any LLM with zero code changes.

Your App → Proxy → [Retrieve & Inject Memories] → LLM Provider

Just change your API endpoint URL - the proxy handles everything automatically.

Context Extension

Context Extension enables unlimited conversation length.

Long conversation → Automatic chunking → Relevant retrieval → Optimized context

Old messages are compressed and stored, then retrieved when relevant to new queries.

Document Ingestion

Import documents and convert them to searchable memories:

• PDFs, images, audio files
• Web pages via URL
• Automatic chunking and indexing