EverOS Memory Framework

EverMind is an open-source ecosystem focused on long-term memory, self-evolving agents, AI-native interfaces, and memory evaluation. It provides a 'research-to-runtime' stack consisting of new memory methods, reusable algorithms, benchmark evidence, and practical agent integrations.

Key components include:

• EverOS: A local memory operating system and runtime for agents and user memory.
• Raven: A self-improving agent harness that brings memory, proactivity, context control, and skill evolution to terminal-native agents.
• EverAlgo: An algorithmic engine providing stateless extraction, ranking, parsing, and memory operators for EverOS.
• HyperMem: Hypergraph memory for long-term dialogue using a topic $\rightarrow$ episode $\rightarrow$ fact retrieval method.
• EverMemBench & EvoAgentBench: Benchmark suites for conversational memory and agent self-evolution.
• MSA (Memory Sparse Attention): Research for scalable latent memory and 100M-token contexts.
• EverMe: A CLI and agent plugin suite for cross-device, cross-agent personal memory.
• evermem-claude-code & everos-plugins: Plugins, skills, and migration tooling for AI coding agents.

The everos Python package is organized into several functional layers. Understanding this layout helps you locate specific logic, such as persistence mechanisms or API entrypoints:

• entrypoints/: Presentation layer containing the CLI and API.
• service/: Application layer responsible for use case orchestration.
• memory/: Domain layer handling extraction, searching, cascading, prompt slots, and models.
• infra/: Infrastructure layer managing persistence via markdown, sqlite, or lancedb.
• component/: Cross-cutting providers for LLMs, embeddings, configuration, and utilities.
• core/: Runtime base providing observability, lifespan management, and context.
• config/: Data layer containing settings, default.toml, and prompt_slots templates.

Each subpackage contains a top-level __init__.py that defines its specific responsibility and public API.

The EverOS HTTP API (v2) provides programmatic access to memory, OME, and knowledge endpoints. All business endpoints are prefixed with /api/v2/ (e.g., /api/v2/memory/, /api/v2/ome/, and /api/v2/knowledge/).

Key Integration Details:

• Versioning: While /api/v2 is the canonical prefix, /api/v1 is maintained as a legacy compatibility alias. New integrations should use /api/v2.
• Content Type: All POST endpoints require Content-Type: application/json using UTF-8 encoding.
• Authentication: The server has no built-in authentication. It binds to 127.0.0.1 by default. Users must implement their own authentication/gateway layer before exposing the API to other interfaces.
• Base URL Configuration: The host and port can be overridden using the EVEROS_API__HOST and EVEROS_API__PORT environment variables, or via --host and --port CLI flags.

# Default Host/Port
Host: 127.0.0.1
Port: 8000

# Overrides
# Via Environment Variables
export EVEROS_API__HOST=0.0.0.0
export EVEROS_API__PORT=9000

# Via CLI Flags
# (Assuming the server binary supports these)
--host 0.0.0.0 --port 9000

EverOS provides a persistent memory layer that can be integrated into various products and workflows. Use cases range from AI coding assistants and browser agents to personalized companions and gaming experiences.

Key categories of integration include:

• AI Coding Assistants: Providing long-term memory for CLI agents like Claude Code, Codex, and Gemini (e.g., evermemos-mcp, EverMem, MCO, Claude Code Plugin).
• Personal Assistants & Companions: Enabling long-term memory for smart glasses, iOS apps, and wearables (e.g., Rokid AI Assistant, Mobi Companion, AI Wearable with Memory).
• Agentic Workflows: Powering multi-agent orchestration (e.g., Hive Orchestrator, Golutra) and specialized data technicians.
• Gaming & Entertainment: Creating memory-aware NPCs, productivity games, and interactive Q&A experiences (e.g., Earth Online, NeuralConnect, Game of Thrones Memories).
• Browser & Computer Use: Carrying personal context across web tasks via browser agents or storing results from screenshot-based computer-use analysis.
• Specialized Tools: Memory graph visualization, Alzheimer's memory assistance, and creative assistants.

A PromptSlot is an abstraction layer between algorithm code (everalgo) and the LLM prompts they use. It allows operators to override default prompts without changing the underlying algorithm code.

EverOS uses a three-layer overlay system to determine the effective prompt. The layer with the highest priority wins:

1. Layer 3: Runtime override (Highest priority) — Supplied at the specific call site (e.g., forcing a specific model).
2. Layer 2: App-level override — Located at ~/.everos/prompt_slots/<name>.yaml. These are per-deployment overrides and are loaded lazily on first reference.
3. Layer 1: Package defaults (Lowest priority) — Located at config/prompt_slots/<name>.yaml. These are bundled with the package and loaded eagerly at startup.

If a slot is disabled or empty in Layers 2 or 3, the system falls back to the algorithm's bundled default.

Effective prompt = layer 3 wins → layer 2 → layer 1.

The EverMem plugin for Claude Code operates using a Stop hook. Claude Code stores all conversations locally in .jsonl (JSON Lines) format. When Claude finishes a response, the plugin reads the transcript file, identifies the most recent complete 'Turn', extracts the user input and the assistant's final text response, and uploads this Q&A pair to the EverMem cloud.

Key Concepts

• Turn: Defined as the sequence from a user message to the assistant's full response. A turn is explicitly marked by a system type line with the subtype turn_duration.
• Transcript Format: A .jsonl file where each line is a JSON object representing a message, tool use, or system event.
• Memory Extraction: The plugin ignores internal reasoning (thinking), tool calls (tool_use), and tool results (tool_result) to focus on the actual conversation content (user text and assistant text blocks).

EverOS enforces a strict separation between how datetimes are stored and how they are displayed to prevent data corruption when timezones change. This is known as the two-zone discipline.

1. The UTC Rail (Storage)

Used for anything persisted to disk (SQLite, LanceDB, OME events). All stored datetimes must be in UTC.

• Goal: Ensure bytes on disk are zone-independent.
• Helpers: get_utc_now, ensure_utc, UtcDatetime.

2. The Display Rail (Presentation)

Used for user-facing outputs like Markdown frontmatter, HTTP API responses, and daily-log filenames.

• Goal: Show users their local 'wall-clock' time.
• Configuration: Controlled by the EVEROS_MEMORY__TIMEZONE environment variable or [memory] timezone in TOML (defaults to UTC).
• Helpers: get_now_with_timezone, today_with_timezone, to_display_tz.

Inviolable Rule: The display timezone must never reach storage. If a user changes their display timezone, existing on-disk UTC rows must remain valid and not misalign.

EverOS follows a strict error propagation strategy:

1. No Catch-and-Wrap: Service and route layers do not catch and wrap exceptions. Exceptions are raised at the layer where they are detected and propagate naturally up the stack.
2. Centralized Handling: The entrypoints layer (specifically entrypoints/api/exception_handlers.py) uses Starlette's MRO dispatch to register per-type exception handlers.
3. Canonical Envelopes: Handlers convert exceptions into a standardized error envelope containing an ErrorCode enum value and the appropriate HTTP status code.
4. Boundary Translation: To prevent third-party library types from leaking into the core logic, exceptions are translated at component boundaries. For example:
   • everalgo.llm.LLMError is translated to LLMServiceError at component/parser/_core.py.
   • Embedding or rerank provider errors are translated to EmbeddingServiceError or RerankServiceError within their respective protocol modules.