Core Concepts

FatHippo is designed to work like human memory—important things stick, irrelevant things fade, and frequently accessed memories get stronger. Here's how it works.

Memory Tiers

Not all memories are equal. FatHippo uses a tiered system to prioritize what gets injected into context windows.

Tier	Description	When Injected
`critical`	Core principles, identity, must-never-forget	Always injected at session start
`working`	Synthesized summaries of related memories	Injected when relevant (synthesize mode)
`high`	Important facts, strong preferences, decisions	Injected when relevant to query
`normal`	Regular memories, facts, events	Injected only if highly relevant

Tip

Critical memories are your agent's "identity layer"—things like user name, timezone, core preferences. These are always available, never decay.

Auto-Promotion

Memories can be promoted automatically based on access patterns:

normal → high: Accessed 5+ times
high → critical: Accessed 10+ times with positive feedback

You can also manually promote memories using the /v1/memories/{id}/lock endpoint.

Memory Types

FatHippo auto-classifies memories into types, each with different decay rates:

Type	Halflife	Examples
`identity`	365 days (never deleted)	Name, location, role, values
`constraint`	180 days	Allergies, hard limits, must-nots
`how_to`	120 days	Procedures, workflows, preferences
`decision`	90 days	Choices made, architecture decisions
`fact`	90 days	Objective knowledge, properties
`preference`	60 days	Likes, dislikes, stylistic preferences
`relationship`	30 days	People, colleagues, social context
`event`	14 days	Specific occurrences, meetings, episodes
`belief`	45 days	Opinions, perspectives, viewpoints

Reinforcement

When something is mentioned multiple times, it becomes a stronger memory. This mirrors the "fire together, wire together" principle in neuroscience.

Frequency Boost

Mention Count	Strength Multiplier
`1st mention`	1.0× (base)
`2nd mention`	1.4× (+40%)
`3rd-5th mention`	+20% each
`6th+ mention`	+5% each (logarithmic)
`Maximum`	2.5× cap

Explicit Feedback

Use the /v1/memories/{id}/reinforce endpoint to give explicit feedback:

// Positive reinforcement (+1)
{"value": 1, "reason": "This was helpful"}

// Negative reinforcement (-1)  
{"value": -1, "reason": "This was outdated"}

Note

Explicit feedback is weighted 5× more than passive access. One positive reinforcement equals 5 passive retrievals.

Memory Decay

Memories that aren't accessed fade over time, following an Ebbinghaus-inspired forgetting curve. This keeps your memory store clean and relevant.

Decay Formula

current_strength = base_strength × (0.9 ^ (days_since_access / halflife))

Lifecycle

Auto-archive: 90 days without access → archived (searchable, deprioritized)
Auto-delete: Strength drops below 0.20 (~210 days of neglect)
Identity protection: Identity memories never auto-delete
Retrieval = strengthening: Every recall bumps strength back up

Warning

Archived memories aren't gone—they're still searchable. They just won't be proactively injected into context. Think of it like moving old files to cold storage.

Namespaces

Namespaces let you organize memories by project, chat, or any logical grouping. Memories in different namespaces are isolated from each other.

# Store in a specific namespace
curl -X POST "https://fathippo.ai/api/v1/memories" \
  -H "Authorization: Bearer mem_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Project uses PostgreSQL", "namespace": "project-alpha"}'

Global Namespace

Identity memories (detected automatically) are stored in a special __global__ namespace. These are available in ALL namespaces—your agent always knows who the user is.

Layered Search

Every search automatically queries both the current namespace AND the global namespace. Results are merged and ranked by relevance.

Sessions

Sessions track conversations over time. They help FatHippo understand:

Which memories were used in which conversations
How long conversations last
Success/failure rates (for analytics)
When to refresh context mid-conversation

Session Lifecycle

1. POST /v1/sessions/start
   → Returns sessionId + initial context (critical + relevant high memories)

2. POST /v1/sessions/{id}/turn (optional, per message pair)
   → Tracks memory usage, returns refresh signal every 5 turns

3. POST /v1/sessions/{id}/end
   → Closes session, records outcome, updates analytics

Tip

Sessions are optional for simple use cases. Use /v1/simple/* endpoints if you just want remember/recall without session tracking.

Encryption Model

All memory content is encrypted at rest using AES-256-GCM with per-user keys. This protects your data against database breaches.

How It Works

You send plaintext content to the API
FatHippo generates embeddings for semantic search
Content is encrypted with your user-specific key
Encrypted content is stored in the database
On retrieval, content is decrypted server-side

What's Protected

Threat	Protected?
`Database breach`	✅ Yes — content encrypted at rest
`SQL injection`	✅ Yes — attacker gets encrypted data only
`Network interception`	✅ Yes — HTTPS required
`API key compromise`	❌ No — protect your API keys!

Warning

Protect your API keys! Anyone with your key can read your memories. Generate separate keys for different agents and revoke them if compromised.

Smart Consolidation

When you store a memory similar to one that already exists (cosine similarity > 0.85), FatHippo suggests consolidation instead of creating duplicates.

// Response when similar memory exists
{
  "status": "consolidation_suggested",
  "newMemory": { "text": "User prefers REST APIs" },
  "similarMemories": [
    {
      "id": "mem_abc",
      "text": "User chose REST over GraphQL",
      "similarity": 0.89
    }
  ],
  "hint": "Add ?force=true to create anyway"
}

The simple API (/v1/simple/remember) auto-consolidates at similarity > 0.90, merging content into the existing memory.

Core Concepts

FatHippo is designed to work like human memory—important things stick, irrelevant things fade, and frequently accessed memories get stronger. Here's how it works.

Memory Tiers

Not all memories are equal. FatHippo uses a tiered system to prioritize what gets injected into context windows.

Tier	Description	When Injected
`critical`	Core principles, identity, must-never-forget	Always injected at session start
`working`	Synthesized summaries of related memories	Injected when relevant (synthesize mode)
`high`	Important facts, strong preferences, decisions	Injected when relevant to query
`normal`	Regular memories, facts, events	Injected only if highly relevant

Tip

Critical memories are your agent's "identity layer"—things like user name, timezone, core preferences. These are always available, never decay.

Auto-Promotion

Memories can be promoted automatically based on access patterns:

normal → high: Accessed 5+ times
high → critical: Accessed 10+ times with positive feedback

You can also manually promote memories using the /v1/memories/{id}/lock endpoint.

Memory Types

FatHippo auto-classifies memories into types, each with different decay rates:

Type	Halflife	Examples
`identity`	365 days (never deleted)	Name, location, role, values
`constraint`	180 days	Allergies, hard limits, must-nots
`how_to`	120 days	Procedures, workflows, preferences
`decision`	90 days	Choices made, architecture decisions
`fact`	90 days	Objective knowledge, properties
`preference`	60 days	Likes, dislikes, stylistic preferences
`relationship`	30 days	People, colleagues, social context
`event`	14 days	Specific occurrences, meetings, episodes
`belief`	45 days	Opinions, perspectives, viewpoints

Reinforcement

When something is mentioned multiple times, it becomes a stronger memory. This mirrors the "fire together, wire together" principle in neuroscience.

Frequency Boost

Mention Count	Strength Multiplier
`1st mention`	1.0× (base)
`2nd mention`	1.4× (+40%)
`3rd-5th mention`	+20% each
`6th+ mention`	+5% each (logarithmic)
`Maximum`	2.5× cap

Explicit Feedback

Use the /v1/memories/{id}/reinforce endpoint to give explicit feedback:

// Positive reinforcement (+1)
{"value": 1, "reason": "This was helpful"}

// Negative reinforcement (-1)  
{"value": -1, "reason": "This was outdated"}

Note

Explicit feedback is weighted 5× more than passive access. One positive reinforcement equals 5 passive retrievals.

Memory Decay

Memories that aren't accessed fade over time, following an Ebbinghaus-inspired forgetting curve. This keeps your memory store clean and relevant.

Decay Formula

current_strength = base_strength × (0.9 ^ (days_since_access / halflife))

Lifecycle

Auto-archive: 90 days without access → archived (searchable, deprioritized)
Auto-delete: Strength drops below 0.20 (~210 days of neglect)
Identity protection: Identity memories never auto-delete
Retrieval = strengthening: Every recall bumps strength back up

Warning

Archived memories aren't gone—they're still searchable. They just won't be proactively injected into context. Think of it like moving old files to cold storage.

Namespaces

Namespaces let you organize memories by project, chat, or any logical grouping. Memories in different namespaces are isolated from each other.

# Store in a specific namespace
curl -X POST "https://fathippo.ai/api/v1/memories" \
  -H "Authorization: Bearer mem_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "Project uses PostgreSQL", "namespace": "project-alpha"}'

Global Namespace

Identity memories (detected automatically) are stored in a special __global__ namespace. These are available in ALL namespaces—your agent always knows who the user is.

Layered Search

Every search automatically queries both the current namespace AND the global namespace. Results are merged and ranked by relevance.

Sessions

Sessions track conversations over time. They help FatHippo understand:

Which memories were used in which conversations
How long conversations last
Success/failure rates (for analytics)
When to refresh context mid-conversation

Session Lifecycle

1. POST /v1/sessions/start
   → Returns sessionId + initial context (critical + relevant high memories)

2. POST /v1/sessions/{id}/turn (optional, per message pair)
   → Tracks memory usage, returns refresh signal every 5 turns

3. POST /v1/sessions/{id}/end
   → Closes session, records outcome, updates analytics

Tip

Sessions are optional for simple use cases. Use /v1/simple/* endpoints if you just want remember/recall without session tracking.

Encryption Model

All memory content is encrypted at rest using AES-256-GCM with per-user keys. This protects your data against database breaches.

How It Works

You send plaintext content to the API
FatHippo generates embeddings for semantic search
Content is encrypted with your user-specific key
Encrypted content is stored in the database
On retrieval, content is decrypted server-side

What's Protected

Threat	Protected?
`Database breach`	✅ Yes — content encrypted at rest
`SQL injection`	✅ Yes — attacker gets encrypted data only
`Network interception`	✅ Yes — HTTPS required
`API key compromise`	❌ No — protect your API keys!

Warning

Protect your API keys! Anyone with your key can read your memories. Generate separate keys for different agents and revoke them if compromised.

Smart Consolidation

When you store a memory similar to one that already exists (cosine similarity > 0.85), FatHippo suggests consolidation instead of creating duplicates.

// Response when similar memory exists
{
  "status": "consolidation_suggested",
  "newMemory": { "text": "User prefers REST APIs" },
  "similarMemories": [
    {
      "id": "mem_abc",
      "text": "User chose REST over GraphQL",
      "similarity": 0.89
    }
  ],
  "hint": "Add ?force=true to create anyway"
}

The simple API (/v1/simple/remember) auto-consolidates at similarity > 0.90, merging content into the existing memory.