Foresight Memory

Foresight memories are prospective - they look forward in time. Unlike episodic memories that record the past, foresight memories have a validity window defined by start_time and end_time. They’re ideal for reminders, deadlines, and future-relevant context. Foresight is also a core component of the MemCell. It lets the system store predictions, plans, and expiring information so your agent can act proactively.

Important: Foresight memory extraction is only available in assistant scene mode. Group chat scenes do not extract foresight memories.

How Foresight Works

When a conversation mentions future events, EverOS extracts foresight memories with time bounds:

User: "Remind me to call John next Tuesday at 2pm"
       ↓
Extracted Foresight Memory:
- Content: "Call John"
- start_time: Next Tuesday 2:00 PM
- end_time: Next Tuesday 3:00 PM (default 1 hour window)

When you search with current_time, only foresight memories within their valid window are returned.

Validity Intervals

Every piece of knowledge has a shelf life. Foresight introduces validity intervals: a start time and an end time that define when the memory is relevant.

Short-term Validity

“I’m in a meeting right now.”

Valid for: 1 hour.
After 1 hour, this fact is archived or treated as past context.

Long-term Validity

“My office is in Berlin.”

Valid for: Indefinite (until contradicted).
The system assumes this stays true unless explicitly changed.

Enabling Proactivity

Foresight turns your agent from reactive to proactive.

Contextual reminders: The system prompts when a deadline is approaching.
Conflict detection: The system flags scheduling conflicts before you commit.
Adaptive behavior: The system adjusts responses based on time-bound intent.

Foresight does not just remember what happened. It helps the agent anticipate what should happen next.

Setup: Enable Foresight Extraction

Foresight extraction requires the assistant scene:

import requests
from datetime import datetime

BASE_URL = "https://api.evermind.ai"
headers = {"Content-Type": "application/json"}

def setup_assistant_with_foresight(user_id: str, assistant_id: str):
    """Configure conversation for foresight extraction."""
    meta = {
        "group_id": f"assistant_{user_id}",
        "group_name": "Personal Assistant",
        "scene": "assistant",  # Required for foresight
        "user_details": [
            {"user_id": user_id, "user_name": "User", "role": "user"},
            {"user_id": assistant_id, "user_name": "Assistant", "role": "assistant"}
        ]
    }

    response = requests.post(
        f"{BASE_URL}/api/v0/memories/conversation-meta",
        json=meta,
        headers=headers
    )
    return response.json()

Creating Foresight Memories

Foresight memories are automatically extracted when conversations mention future events:

import uuid
from datetime import datetime

def store_message(group_id: str, sender: str, content: str):
    """Store a message that may create foresight memories."""
    message = {
        "group_id": group_id,
        "group_name": "Personal Assistant",
        "message_id": str(uuid.uuid4()),
        "create_time": datetime.now().isoformat() + "Z",
        "sender": sender,
        "sender_name": "User" if sender != "assistant" else "Assistant",
        "content": content
    }

    response = requests.post(
        f"{BASE_URL}/api/v0/memories",
        json=message,
        headers=headers
    )
    return response.json()

# Messages that create foresight memories
store_message("assistant_alice", "user_alice",
    "Remind me to submit the report by Friday 5pm")

store_message("assistant_alice", "user_alice",
    "I have a dentist appointment next Monday at 10am")

store_message("assistant_alice", "user_alice",
    "The project deadline is March 15th")

store_message("assistant_alice", "user_alice",
    "Don't forget to call Mom this weekend")

Time Validity Windows

Foresight memories have start_time and end_time fields that define when they’re relevant:

Example Statement	start_time	end_time
”Call John at 2pm Tuesday”	Tuesday 2:00 PM	Tuesday 3:00 PM
”Submit report by Friday”	Now	Friday 11:59 PM
”Doctor appointment March 10”	March 10 12:00 AM	March 10 11:59 PM
”Review code this week”	Now	End of week

Searching with Time Context

Use current_time parameter to filter foresight memories by relevance:

from datetime import datetime

def get_current_reminders(user_id: str) -> list:
    """Get foresight memories valid at current time."""
    search_params = {
        "user_id": user_id,
        "query": "reminder appointment deadline task",
        "retrieve_method": "hybrid",
        "top_k": 10,
        "memory_types": ["foresight"],
        "current_time": datetime.now().isoformat() + "Z"  # Filter by current time
    }

    response = requests.get(
        f"{BASE_URL}/api/v0/memories/search",
        json=search_params,
        headers=headers
    )

    result = response.json()
    return result.get("result", {}).get("memories", [])

# Get reminders relevant right now
reminders = get_current_reminders("user_alice")
for r in reminders:
    print(f"- {r.get('memory_content')}")

Time-Based Filtering Behavior

# Scenario: It's Monday 9am

# This foresight memory is INCLUDED (within window):
# "Dentist appointment Monday 10am" (start: Mon 10am, end: Mon 11am)

# This foresight memory is EXCLUDED (not yet started):
# "Submit report Friday 5pm" (start: Fri 4pm, end: Fri 5pm)
# But if searching for "what do I have coming up", it may still appear

# This foresight memory is EXCLUDED (already passed):
# "Call John last Friday" (end_time in the past)

Use Cases

Personal Reminders

class ReminderAssistant:
    def __init__(self, user_id: str):
        self.user_id = user_id
        self.group_id = f"assistant_{user_id}"

    def check_due_reminders(self) -> list:
        """Check for reminders due now or soon."""
        search_params = {
            "user_id": self.user_id,
            "group_ids": [self.group_id],
            "query": "reminder remember don't forget call meeting appointment",
            "retrieve_method": "hybrid",
            "top_k": 20,
            "memory_types": ["foresight"],
            "current_time": datetime.now().isoformat() + "Z"
        }

        response = requests.get(
            f"{BASE_URL}/api/v0/memories/search",
            json=search_params,
            headers=headers
        )

        return response.json().get("result", {}).get("memories", [])

    def get_upcoming_context(self, query: str) -> list:
        """Get upcoming events relevant to a query."""
        search_params = {
            "user_id": self.user_id,
            "query": query,
            "retrieve_method": "hybrid",
            "top_k": 5,
            "memory_types": ["foresight"],
            "current_time": datetime.now().isoformat() + "Z"
        }

        response = requests.get(
            f"{BASE_URL}/api/v0/memories/search",
            json=search_params,
            headers=headers
        )

        return response.json().get("result", {}).get("memories", [])


# Usage
assistant = ReminderAssistant("user_alice")

# At start of day, check what's due
due_today = assistant.check_due_reminders()
print("Today's reminders:")
for r in due_today:
    print(f"  - {r.get('memory_content')}")

# When user asks about meetings
user_message = "What meetings do I have coming up?"
upcoming = assistant.get_upcoming_context("meeting appointment call")

Deadline Tracking

def get_upcoming_deadlines(user_id: str, days_ahead: int = 7) -> list:
    """Get deadlines within the next N days."""
    # Search for deadline-related foresight memories
    search_params = {
        "user_id": user_id,
        "query": "deadline due submit complete finish by",
        "retrieve_method": "hybrid",
        "top_k": 20,
        "memory_types": ["foresight"],
        "current_time": datetime.now().isoformat() + "Z"
    }

    response = requests.get(
        f"{BASE_URL}/api/v0/memories/search",
        json=search_params,
        headers=headers
    )

    memories = response.json().get("result", {}).get("memories", [])

    # Filter/sort by urgency (would need access to end_time)
    return memories

# Check upcoming deadlines
deadlines = get_upcoming_deadlines("user_alice")
print(f"Found {len(deadlines)} upcoming deadlines")

Contextual Follow-ups

def get_follow_up_context(user_id: str, topic: str) -> dict:
    """Get both past context and upcoming commitments for a topic."""

    # Past conversations about this topic
    past_search = {
        "user_id": user_id,
        "query": topic,
        "retrieve_method": "hybrid",
        "top_k": 5,
        "memory_types": ["episodic_memory"]
    }

    # Future commitments related to this topic
    future_search = {
        "user_id": user_id,
        "query": topic,
        "retrieve_method": "hybrid",
        "top_k": 5,
        "memory_types": ["foresight"],
        "current_time": datetime.now().isoformat() + "Z"
    }

    past_response = requests.get(
        f"{BASE_URL}/api/v0/memories/search",
        json=past_search,
        headers=headers
    )

    future_response = requests.get(
        f"{BASE_URL}/api/v0/memories/search",
        json=future_search,
        headers=headers
    )

    return {
        "past_context": past_response.json().get("result", {}).get("memories", []),
        "upcoming": future_response.json().get("result", {}).get("memories", [])
    }


# When user mentions a project
context = get_follow_up_context("user_alice", "Phoenix project")
print("Past discussions:", len(context["past_context"]))
print("Upcoming deadlines/meetings:", len(context["upcoming"]))

Proactive Reminder System

Build a system that proactively checks and surfaces reminders:

import asyncio
from datetime import datetime, timedelta

class ProactiveReminderService:
    """Background service that checks for due reminders."""

    def __init__(self, check_interval_minutes: int = 15):
        self.check_interval = check_interval_minutes * 60
        self.notified = set()  # Track already-notified reminders

    async def start(self, user_ids: list):
        """Start checking reminders for users."""
        while True:
            for user_id in user_ids:
                await self._check_user_reminders(user_id)
            await asyncio.sleep(self.check_interval)

    async def _check_user_reminders(self, user_id: str):
        """Check and notify user of due reminders."""
        search_params = {
            "user_id": user_id,
            "query": "reminder appointment meeting deadline",
            "retrieve_method": "hybrid",
            "top_k": 10,
            "memory_types": ["foresight"],
            "current_time": datetime.now().isoformat() + "Z"
        }

        response = requests.get(
            f"{BASE_URL}/api/v0/memories/search",
            json=search_params,
            headers=headers
        )

        memories = response.json().get("result", {}).get("memories", [])

        for mem in memories:
            mem_id = mem.get("memory_id")
            if mem_id not in self.notified:
                await self._send_notification(user_id, mem)
                self.notified.add(mem_id)

    async def _send_notification(self, user_id: str, memory: dict):
        """Send notification to user."""
        content = memory.get("memory_content", "")
        print(f"[NOTIFICATION] {user_id}: {content}")
        # Implement actual notification (push, email, etc.)

Limitations and Considerations

Foresight memory has specific limitations you should understand:

Scene Requirement

# Foresight extraction ONLY works with assistant scene
meta = {
    "scene": "assistant",  # Required
    ...
}

# Group chat scene does NOT extract foresight
meta = {
    "scene": "group_chat",  # No foresight extraction
    ...
}

Extraction Accuracy

Foresight extraction depends on clear temporal references in the conversation:

# Good: Clear temporal reference
"Remind me to call John next Tuesday at 2pm"  # Extracted with precise time

# Ambiguous: May not extract correctly
"I should probably call John sometime"  # No clear time reference

# Complex: May partially extract
"Let's meet either Monday or Tuesday, I'll confirm later"  # Uncertain

Time Zone Handling

Be explicit about time zones in your application:

from datetime import datetime, timezone

# Always use UTC for current_time parameter
current_time = datetime.now(timezone.utc).isoformat()

# Or use explicit timezone
import pytz
tz = pytz.timezone("America/New_York")
current_time = datetime.now(tz).isoformat()

Best Practices

Time Filtering Strategy

Always include current_time when searching foresight memories to get relevant results.

# Always include current_time for foresight searches
search_params = {
    "memory_types": ["foresight"],
    "current_time": datetime.now().isoformat() + "Z"
}

Combining Memory Types

Search foresight alongside other memory types for complete context.

# Combined search for full context
search_params = {
    "memory_types": ["episodic_memory", "profile", "foresight"],
    "current_time": datetime.now().isoformat() + "Z"
}

Reminder Acknowledgment

Store acknowledgments to track reminder completion.

# User acknowledges a reminder
store_message(group_id, user_id,
    "I've completed the report submission reminder")
# Creates episodic memory showing task completion

Getting started

Core Concepts

Essential Features

Foresight Memory

How Foresight Works

Validity Intervals

Short-term Validity

Long-term Validity

Enabling Proactivity

Setup: Enable Foresight Extraction

Creating Foresight Memories

Time Validity Windows

Searching with Time Context

Time-Based Filtering Behavior

Use Cases

Personal Reminders

Deadline Tracking

Contextual Follow-ups

Proactive Reminder System

Limitations and Considerations

Scene Requirement

Extraction Accuracy

Time Zone Handling

Best Practices

Next Steps

Personal Assistant

AI Tutor

​How Foresight Works

​Validity Intervals

Short-term Validity

Long-term Validity

​Enabling Proactivity

​Setup: Enable Foresight Extraction

​Creating Foresight Memories

​Time Validity Windows

​Searching with Time Context

​Time-Based Filtering Behavior

​Use Cases

​Personal Reminders

​Deadline Tracking

​Contextual Follow-ups

​Proactive Reminder System

​Limitations and Considerations

​Scene Requirement

​Extraction Accuracy

​Time Zone Handling

​Best Practices

​Next Steps

Personal Assistant

AI Tutor

How Foresight Works

Validity Intervals

Enabling Proactivity

Setup: Enable Foresight Extraction

Creating Foresight Memories

Time Validity Windows

Searching with Time Context

Time-Based Filtering Behavior

Use Cases

Personal Reminders

Deadline Tracking

Contextual Follow-ups

Proactive Reminder System

Limitations and Considerations

Scene Requirement

Extraction Accuracy

Time Zone Handling

Best Practices

Next Steps