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

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 Enhancements

Improve retrieval with these options:

• query_rewrite: Expands your query for better recall
• hybrid_search: Combines keyword and semantic matching
• temporal_boost: Prioritizes recent memories

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