# https://github.com/EverMind-AI/EverOS Project Manual
Generated at: 2026-06-23 07:44:18 UTC
## Table of Contents
- [Overview & Quick Start](#page-overview)
- [System Architecture & Storage Layout](#page-architecture)
- [Memory Lifecycle: Extract, Search, and Cascade](#page-memory)
- [APIs, Integrations, and Benchmarks](#page-api-bench)
## Overview & Quick Start
### Related Pages
Related topics: [System Architecture & Storage Layout](#page-architecture), [APIs, Integrations, and Benchmarks](#page-api-bench)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/EverMind-AI/EverOS/blob/main/README.md)
- [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)
- [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)
- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)
- [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)
- [use-cases/game-of-throne-demo/backend/package.json](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/package.json)
- [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
- [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts)
- [use-cases/game-of-throne-demo/frontend/src/types/index.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/types/index.ts)
- [use-cases/game-of-throne-demo/frontend/src/components/MessageList.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/MessageList.tsx)
- [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)
# Overview & Quick Start
EverOS is an open-source AI memory infrastructure project maintained by [EverMind-AI](https://github.com/EverMind-AI/EverOS). It provides persistent, agentic memory services that any LLM-backed application can call to store, retrieve, and reason over long-lived conversational context. The project ships a Python service, an HTTP API, a contract-first CLI, and a curated gallery of reference use-cases.
## What EverOS Provides
EverOS exposes two primary surfaces for callers:
- **HTTP API** — versioned routes (v1 and v3) under `src/everos/entrypoints/api/` for ingesting messages and searching stored memories. The memorize route, for example, takes a `MemorizeAddRequest` with `session_id`, `app_id`, `project_id`, and a list of `MessageItemDTO` objects (`sender_id`, `role`, `timestamp` in milliseconds, `content`, optional `tool_calls`). Source: [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py).
- **CLI** — contract-first entry point with JSON output by default and a machine-readable `--describe` mode. Source: [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py). Each subcommand is a `typer.Typer` instance mounted into the main CLI app. Source: [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py).
### Identifier Safety (EverOS 1.0.1)
Release 1.0.1 hardens caller-supplied identifiers against path traversal. `sender_id` now shares the path-safety guard used for `app_id` and `project_id`: a character whitelist plus rejection of the `.` and `..` tokens. The whitelist admits `@` and `+` so email-style ids and plus-addressing still pass. The `MarkdownWriter` additionally rejects any write target that resolves outside the allow-listed output directory, providing defense-in-depth write containment.
## Architecture at a Glance
The following diagram summarizes the main components that ship in this repository and the surfaces an integrator typically touches.
```mermaid
flowchart LR
Client[Client App / Agent] -->|HTTP| API[EverOS API\nsrc/everos/entrypoints/api]
Client -->|CLI| CLI[EverOS CLI\nsrc/everos/entrypoints/cli]
API --> Core[Memory Core\nAlgo + Storage]
CLI --> Core
Core --> MemStore[(Memory Store)]
Core --> LLM[LLM Provider]
API -. responses .-> UCs[Use-case Demos\nuse-cases/]
UCs -->|cloud or local| MemSvc[EverMind Cloud API]
```
## Quick Start
### 1. Install and Run the Service
Clone the repository and install the Python package:
```bash
git clone https://github.com/EverMind-AI/EverOS.git
cd EverOS
pip install -e .
```
The package exposes both `everos-api` (HTTP entry point) and `everos-cli` (command-line entry point). Source: [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py).
### 2. Try the CLI
The CLI is contract-first with JSON output by default:
```bash
everos-cli --describe
everos-cli memorize --session-id demo-1 --input messages.json
```
Use `--describe` to inspect the machine-readable schema before sending data. Granular exit codes distinguish validation errors from runtime failures. Source: [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py).
### 3. Call the HTTP API
Post a memorize request with the shape defined in [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py). The request payload requires a `session_id` plus one or more `MessageItemDTO` entries; `app_id` and `project_id` default to `"default"` and `sender_id` is constrained to a path-safe charset (`sender_id: PathSafeId = Field(..., pattern=_PATH_SAFE_CHARSET)`).
### 4. Explore a Reference Use-Case
The fastest way to see EverOS in action is the bundled **Game of Thrones Memory Demo**. Source: [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md).
- **Frontend**: React 18 + TypeScript + Vite
- **Backend**: Node.js + Express, run with Bun (`bun --watch src/server.ts`). Source: [use-cases/game-of-throne-demo/backend/package.json](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/package.json)
- **Memory backend**: EverMind Cloud API (the `IMemoryService` interface defines `retrieveMemories`, `isAvailable`, and an optional `clearMemories`). Source: [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
The demo streams two responses side-by-side via Server-Sent Events — one *with memory* and one *without* — so you can visually compare grounding quality. Follow-up questions are generated by an OpenAI call after each answer completes. Source: [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts). The streaming UI consumes typed `SSEEvent` payloads with discriminators such as `'memories' | 'token' | 'done' | 'followups' | 'error' | 'complete'`. Source: [use-cases/game-of-throne-demo/frontend/src/types/index.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/types/index.ts).
## Use-Case Gallery
The `use-cases/` directory bundles reference integrations so you can see how different products consume EverOS. Notable entries include:
- **Claude Code Plugin** — exposes an `evermem_search` MCP tool and an `/ask` slash command that combines memory hits with current-session context. The ask prompt instructs the model to be honest about sources and to admit uncertainty. Source: [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md).
- **Game of Thrones Demo** — interactive Q&A over a book corpus with side-by-side memory comparison. Source: [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md).
- **Memory Graph Visualization** — a frontend graph explorer for stored entities and relationships.
- **Hive Orchestrator**, **Reunite**, **Mobi Companion**, **AI Coding Assistants with EverOS**, **MemoCare**, **NeuralConnect**, and several more — each linked in the curated gallery. Source: [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md).
## Community Highlights & Known Gaps
Several recurring themes from community discussions are worth noting before you integrate:
- **LoCoMo benchmark interest** — users regularly ask for the per-question response trace and the exact answer prompt used for the reported 92.3% LoCoMo result. When reproducing numbers, document the prompt and decoding settings.
- **Token accounting** — community members ask whether published token counts cover both memory generation and retrieval-augmented answering, or only one phase. Track both phases separately when reporting your own numbers.
- **Missing delete/reset endpoints** — issue #14 requests APIs for deleting and resetting memories to support chat editing and context clearing in chat products. As of this release, the v3 API still focuses on `memorize` and `search`; check the current route list before designing UIs that need destructive operations.
- **Pipeline runtime** — issue #195 reports stage 2 of the HyperMem evaluation pipeline taking more than four hours. Plan accordingly when running the benchmark end-to-end.
## See Also
- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py) — request schema for the memorize endpoint
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py) — CLI design contract
- [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md) — full use-case gallery and contribution rules
- [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md) — end-to-end demo walkthrough
---
## System Architecture & Storage Layout
### Related Pages
Related topics: [Overview & Quick Start](#page-overview), [Memory Lifecycle: Extract, Search, and Cascade](#page-memory)
Related Source Files
The following source files were used to generate this page:
- [docs/architecture.md](https://github.com/EverMind-AI/EverOS/blob/main/docs/architecture.md)
- [docs/storage_layout.md](https://github.com/EverMind-AI/EverOS/blob/main/docs/storage_layout.md)
- [docs/cascade_runbook.md](https://github.com/EverMind-AI/EverOS/blob/main/docs/cascade_runbook.md)
- [docs/engineering.md](https://github.com/EverMind-AI/EverOS/blob/main/docs/engineering.md)
- [src/everos/README.md](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/README.md)
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)
- [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)
- [src/everos/entrypoints/api/app.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/app.py)
- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)
- [src/everos/infra/ome/engine.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/infra/ome/engine.py)
# System Architecture & Storage Layout
## Overview
EverOS is the open-source AI memory infrastructure behind EverMind. It exposes a layered Python package (`everos`) that turns raw conversation content into searchable, persistent memory, and it does so behind two thin presentation surfaces — a CLI and an HTTP API. The codebase enforces a single-direction dependency rule so that domain logic never imports from presentation, and infrastructure adapters never leak into higher layers ([`src/everos/README.md`](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/README.md)).
The architecture has three high-level goals:
1. **Stable contracts.** Both CLI and API speak the same `Memorize` / `Search` data model so that downstream agents can swap transports without code changes.
2. **Pluggable persistence.** The `infra/` package contains three persistence backends — Markdown files, SQLite, and LanceDB — selected by configuration rather than hard-coded imports.
3. **Defensive defaults.** Identifier validation, write containment, and path-safety guards are applied at the edge so unsafe caller input never reaches the storage layer ([EverOS 1.0.1 release notes](https://github.com/EverMind-AI/EverOS/releases)).
## Layered Architecture
The `everos` package is organized into seven sub-packages, each with a single responsibility ([`src/everos/README.md`](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/README.md)):
| Layer | Sub-package | Responsibility |
|-------|-------------|----------------|
| Presentation | `entrypoints/` | CLI and HTTP API surfaces |
| Application | `service/` | Use-case orchestration |
| Domain | `memory/` | Extract, search, cascade, prompt slots, models |
| Infrastructure | `infra/persistence/{markdown,sqlite,lancedb}` | Storage adapters |
| Cross-cutting | `component/` | LLM, embedding, config, utils providers |
| Runtime | `core/` | Observability, lifespan, context |
| Data | `config/` | `Settings`, `default.toml`, prompt-slot templates |
The dependency rule is unidirectional and is enforced in CI by `import-linter`:
```mermaid
flowchart TD
A[entrypoints
CLI + API] --> B[service
orchestration]
B --> C[memory
extract + search + cascade]
C --> D[infra/persistence
markdown · sqlite · lancedb]
C --> E[component
llm · embedding · utils]
A --> E
B --> E
C --> F[core
observability · lifespan]
C --> G[config
Settings + default.toml]
```
This shape keeps presentation thin and lets new storage backends be added without touching domain code.
## Storage Layout
The `infra/persistence/` package contains three adapters selected at runtime through `Settings`. Each adapter is responsible for a different shape of data:
- **Markdown** — durable, human-readable long-form content such as episode narratives, summaries, and group records. Written through `MarkdownWriter`.
- **SQLite** — structured metadata, foreign-key relations between sessions, groups, episodes, and atomic counters.
- **LanceDB** — vector embeddings for semantic retrieval and cascade search.
The vector store is the primary retrieval substrate during the search phase, while Markdown and SQLite keep the canonical record and citation chain. Cascade runbooks describe how to rebalance, compact, and recover these stores ([`docs/cascade_runbook.md`](https://github.com/EverMind-AI/EverOS/blob/main/docs/cascade_runbook.md)).
### Security hardening in 1.0.1
Two defense-in-depth changes shipped in EverOS 1.0.1 directly affect the storage layout:
- **Path-traversal guard on caller identifiers.** `sender_id` now uses the same `PathSafeId` pattern as `app_id` and `project_id`. Identifiers must match a character whitelist and must not equal `.` or `..`. The whitelist admits `@` and `+` so email-style ids and plus-addressing still pass.
- **MarkdownWriter containment.** Any write target that resolves outside the configured Markdown root is rejected before the file system is touched.
Together these changes mean a malicious or buggy caller can no longer escape the on-disk sandbox via the API ([`src/everos/entrypoints/api/routes/memorize.py`](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)).
## API & CLI Entrypoints
### HTTP API
The HTTP surface is mounted from `entrypoints/api/app.py` and registers route modules such as `memorize.py`. The `MemorizeAddRequest` model demonstrates the contract shape:
```python
class MemorizeAddRequest(BaseModel):
session_id: str = Field(..., min_length=1, max_length=128)
app_id: PathSafeId = Field(default="default", pattern=_PATH_SAFE_CHARSET)
project_id: PathSafeId = Field(default="default", pattern=_PATH_SAFE_CHARSET)
messages: list[MessageItemDTO]
```
`MessageItemDTO` accepts `text`, `image`, `audio`, `doc`, `pdf`, `html`, and `email` content pieces and requires an explicit Unix-epoch timestamp in milliseconds. `extra="forbid"` on every DTO prevents silent contract drift ([`src/everos/entrypoints/api/routes/memorize.py`](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)).
Community issue #14 ("Add APIs for Deleting/Resetting Memories to Support Chat Editing and Context Clearing") notes that the V3 surface currently only exposes `memorize` and `search`; deletion and reset endpoints are a frequently requested extension. Until those land, integrators typically clear context by isolating `session_id` or by resetting the local SQLite store through the CLI.
### CLI
The CLI is contract-first: it emits JSON by default, supports a `--describe` mode for machine-readable schemas, and uses granular exit codes suitable for scripting ([`src/everos/entrypoints/cli/__init__.py`](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)). Each subcommand group lives in `entrypoints/cli/commands/` and exposes a `typer.Typer` instance that the root CLI mounts ([`src/everos/entrypoints/cli/commands/__init__.py`](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)).
## Common Failure Modes
A few patterns show up repeatedly in community discussions and the runbooks:
- **Long-running pipeline stages.** Issue #195 reports HyperMem Evaluation Pipeline stage 2 taking over four hours. The cascade runbook documents expected durations per stage and where to look for stuck LLM or embedding calls ([`docs/cascade_runbook.md`](https://github.com/EverMind-AI/EverOS/blob/main/docs/cascade_runbook.md)).
- **Token accounting.** Issue #56 asks whether the ~2.5K token figure reported for LoCoMo (gpt-4o-mini) is generation-only or end-to-end. The architecture separates extraction, indexing, and answer-time retrieval so each phase can be measured independently through `component/` providers.
- **Path traversal via identifier fields.** Mitigated in 1.0.1 by extending the `PathSafeId` whitelist to `sender_id` and tightening `MarkdownWriter` write targets.
## See Also
- [Architecture overview](https://github.com/EverMind-AI/EverOS/blob/main/docs/architecture.md)
- [Storage layout reference](https://github.com/EverMind-AI/EverOS/blob/main/docs/storage_layout.md)
- [Cascade operations runbook](https://github.com/EverMind-AI/EverOS/blob/main/docs/cascade_runbook.md)
- [Engineering practices](https://github.com/EverMind-AI/EverOS/blob/main/docs/engineering.md)
- [Migration guide to 1.0.0](https://github.com/EverMind-AI/EverOS/blob/main/docs/migration-to-1.0.0.md)
- [Use cases gallery](../use-cases/README.md)
---
## Memory Lifecycle: Extract, Search, and Cascade
### Related Pages
Related topics: [System Architecture & Storage Layout](#page-architecture), [APIs, Integrations, and Benchmarks](#page-api-bench)
Related Source Files
The following source files were used to generate this page:
- [src/everos/entrypoints/api/routes/get.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/get.py)
- [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
- [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts)
- [use-cases/game-of-throne-demo/frontend/src/types/index.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/types/index.ts)
- [use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx)
- [use-cases/game-of-throne-demo/frontend/src/components/MemoryPanel.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/MemoryPanel.tsx)
- [use-cases/claude-code-plugin/commands/help.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/help.md)
- [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)
- [use-cases/openher/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/openher/README.md)
# Memory Lifecycle: Extract, Search, and Cascade
## Overview
EverOS exposes its long-term memory layer as a three-stage pipeline: **Extract** (turn raw text into structured memories), **Search** (retrieve relevant memories for a query), and **Cascade** (manage the resulting records through listing, reset, and downstream propagation). Together these stages form the lifecycle that every consumer application — chat assistants, coding agents, narrative demos, multi-agent platforms — relies on.
The platform is intentionally API-first. The HTTP surface is mounted under `/api/v1/memory/*` and `/api/v3/agentic/*`, while SDK-style service abstractions (e.g., `IMemoryService`) hide those routes from application code. The Claude Code plugin, the Game-of-Thrones story demo, and the OpenHer companion all wrap the same lifecycle behind familiar product affordances.
## Memory Extraction (Memorize)
The Extract stage turns unstructured content — chat turns, document chunks, agent traces — into canonical `Memory` records. The shape of those records is fixed at the SDK boundary so downstream stages can rely on a stable contract:
```typescript
interface Memory {
id: string;
content: string;
metadata: { bookTitle: string; chapterNumber?: number; chapterName?: string };
relevanceScore?: number;
subject?: string; // concise headline
summary?: string; // short summary paragraph
episode?: string; // detailed narrative with timestamps
originalContent?: string; // verbatim source text
}
```
Source: [use-cases/game-of-throne-demo/frontend/src/types/index.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/types/index.ts)
Four payload fields (`subject`, `summary`, `episode`, `originalContent`) are surfaced to the LLM at answer time, which lets the answering model cite either the compressed abstraction or the literal source. The extraction entry point is the V3 agentic route `/api/v3/agentic/memorize` referenced by integration partners; only this route currently covers the "add" half of the lifecycle, which is why feature requests such as issue #14 (a V3 delete/reset counterpart) remain open community work.
## Memory Search and Retrieval
The Search stage is mediated by a typed service interface so that products can swap implementations (cloud, local, in-memory) without changing call sites:
```typescript
interface IMemoryService {
retrieveMemories(query: string, limit?: number): Promise;
isAvailable(): Promise;
clearMemories?(): Promise;
}
```
Source: [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
Results are then injected into the LLM system prompt as numbered citations. The "with memory" prompt in the demo explicitly instructs the model to cite `[1]`, `[2]`, … and to fall back to a knowledge-only answer when memories are insufficient; a parallel "without memory" prompt is used for the A/B comparison pane.
Source: [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts)
On the server, paginated browsing is exposed by `POST /api/v1/memory/get`. It validates a `GetRequest` DTO, dispatches to the service layer, and returns a `GetResponse` envelope untouched. Filter-DSL violations are translated into HTTP 422 with the compile error verbatim, which is why `FilterError` is imported from `everos.memory.search`.
Source: [src/everos/entrypoints/api/routes/get.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/get.py)
On the client, the Game-of-Thrones demo renders retrieved memories as a sidebar of `MemoryCard` chips with expandable original-text toggles, and the `Citation` component lets the user click `[n]` to scroll the matching card into view.
Source: [use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx), [use-cases/game-of-throne-demo/frontend/src/components/MemoryPanel.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/MemoryPanel.tsx)
The Claude Code plugin treats Search as the dominant step in answering: it calls `evermem_search` with up to three keyword variants, evaluates each batch, and only then composes a response that clearly attributes each claim to a memory, the current session, or general knowledge.
Source: [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)
## Memory Cascade: Listing, Reset, and Propagation
The Cascade stage is what makes memory *manageable*. It covers (a) paginated listing via `/api/v1/memory/get`, (b) optional `clearMemories()` reset on the service interface, and (c) downstream propagation into personality, retrieval, and UI layers.
```mermaid
flowchart LR
A[Raw input] --> B[Extract /api/v3/agentic/memorize]
B --> C[Memory store]
C --> D[Search via IMemoryService.retrieveMemories]
D --> E[LLM answer with citations]
C --> F[/api/v1/memory/get listing]
C --> G[clearMemories reset]
G --> H[Cascade downstream dependents]
```
The 1.0.1 release tightened identifier handling so that `app_id`, `project_id`, and `sender_id` all pass a character whitelist and reject `.` / `..` traversal, and `MarkdownWriter` rejects any write target outside an allow-list. This matters for the Cascade stage because resets, exports, and per-tenant dumps all hit the filesystem; the new containment rules prevent a malicious caller from steering those writes outside the intended directory.
The OpenHer companion illustrates why Cascade is more than a delete button. Its three-layer memory (style, local facts, long-term episodic) feeds four behavioral scalars — relationship depth, emotional valence, trust, and pending foresight. When an episodic record is rewritten or reset, those scalars have to be recomputed downstream; otherwise the companion keeps stale signals about a "stranger" who has actually become an "old friend."
Source: [use-cases/openher/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/openher/README.md)
## Operational Notes and Known Gaps
- **Delete/Reset parity.** The V3 API currently exposes `memorize` and retrieval but no first-class `delete` or `reset` endpoint. Issue #14 documents the gap and is the canonical reference for production integrators building chat-edit and context-clearing flows.
- **Token accounting.** Reported per-query token usage (e.g., 2.5K on LoCoMo with `gpt-4o-mini`) reflects the full retrieve-then-answer path, not extraction. Issue #56 captures this clarification.
- **Long-running pipelines.** The HyperMem evaluation Stage 2 routinely takes more than four hours (issue #195). Treat memory extraction as a batch workload and budget accordingly.
- **Identifier safety.** All caller-supplied identifiers — `app_id`, `project_id`, `sender_id` — must pass the path-safety whitelist introduced in 1.0.1; failures surface as a validation error before any read or write is attempted.
## See Also
- [Memory Model and Storage Internals](#)
- [API Reference: V3 Agentic Routes](#)
- [Use Cases and Integrations](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
---
## APIs, Integrations, and Benchmarks
### Related Pages
Related topics: [Overview & Quick Start](#page-overview), [Memory Lifecycle: Extract, Search, and Cascade](#page-memory)
Related Source Files
The following source files were used to generate this page:
- [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py)
- [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py)
- [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py)
- [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
- [use-cases/game-of-throne-demo/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)
- [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts)
- [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts)
- [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)
# APIs, Integrations, and Benchmarks
EverOS ships with a layered public surface: a contract-first HTTP API, a CLI with JSON-by-default output, a catalog of plug-in use cases, and evaluation pipelines for measuring retrieval quality. This page documents the entry points a developer or evaluator touches, the supported integrations, and how the project is benchmarked.
## Public API Surface
The HTTP API is defined in Pydantic models under `src/everos/entrypoints/api/routes/`. The primary ingestion endpoint is `/api/v3/agentic/memorize`, which accepts a `MemorizeAddRequest` containing a `session_id`, an `app_id`, an optional `project_id`, and a list of `MessageItemDTO` messages. Source: [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py).
Each `MessageItemDTO` includes a `sender_id` (now guarded with the same path-safety whitelist applied to `app_id` and `project_id` in EverOS 1.0.1), a `role` of `user | assistant | tool`, a `timestamp` in milliseconds, and either a string or a list of structured `ContentItemDTO` pieces. `ContentItemDTO` supports `text`, `image`, `audio`, `doc`, `pdf`, `html`, and `email` modalities. The `model_config = ConfigDict(extra="forbid")` setting means unknown fields are rejected at the boundary. Source: [src/everos/entrypoints/api/routes/memorize.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/api/routes/memorize.py).
| Endpoint | Direction | Purpose | Notes |
| --- | --- | --- | --- |
| `POST /api/v3/agentic/memorize` | Ingest | Persist session messages | Pydantic-validated, path-safe ids |
| CLI `--describe` | Out-of-band | Machine-readable schema | JSON by default, granular exit codes |
| Cloud `/memorize` (EverMind) | Ingest | Hosted alternative to self-hosted API | Used by external demos |
The V3 API currently exposes ingest and retrieval routes, but community issue #14 highlights a missing capability: there are no public endpoints for deleting or resetting memories to support chat editing and context clearing. This is a known gap for production chat applications that need to invalidate stale context. Source: [community context #14].
## Command-Line Interface
The CLI is a contract-first front end designed for scripting and CI evaluation. It emits JSON by default, supports a `--describe` flag for machine-readable schema discovery, and uses granular exit codes for success vs. partial failure. Source: [src/everos/entrypoints/cli/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/__init__.py). Subcommands are mounted via `typer.Typer` instances defined under `src/everos/entrypoints/cli/commands/`. Source: [src/everos/entrypoints/cli/commands/__init__.py](https://github.com/EverMind-AI/EverOS/blob/main/src/everos/entrypoints/cli/commands/__init__.py).
The CLI is the canonical entry point for running benchmark pipelines such as LoCoMo and HyperMem, where deterministic JSON output and exit-code semantics are required for orchestration.
## Reference Integrations and Use Cases
The repository ships a catalog of reference integrations under `use-cases/`. They illustrate how the API and MCP servers are consumed in real products. Source: [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md).
```mermaid
flowchart LR
Client["Chat / Agent Client"] -->|POST /api/v3/agentic/memorize| API["EverOS API"]
Client -->|MCP tool call| MCP["EverOS MCP Server"]
API --> Store["Memory Store"]
MCP --> Store
Store -->|retrieve| Client
Store -->|graph view| Viz["Memory Graph Visualization"]
```
Notable reference integrations include:
- **Game of Thrones Memories Demo** — a side-by-side Q&A application that streams two responses, one grounded in retrieved memories and one without. It exposes an `IMemoryService` interface with `retrieveMemories`, `isAvailable`, and an optional `clearMemories` method. Source: [use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/IMemoryService.ts). The frontend renders interactive citation chips that link each `memory [n]` reference back to the source passage, with streaming via SSE. Source: [use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/frontend/src/components/ComparisonView.tsx).
- **Claude Code Plugin** — exposes `evermem_search` as an MCP tool so the assistant can answer questions by combining prior-session memories with current context. The `ask` command instructs the model to issue up to three searches and to be explicit about which source it cites. Source: [use-cases/claude-code-plugin/commands/ask.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md).
- **Earth Online**, **Hive Orchestrator**, **Mobi Companion**, **MemoCare**, and **Reunite** — third-party demos that wire EverOS into productivity games, multi-agent IDEs, AI wearables, accessibility assistants, and family-history search respectively. Source: [use-cases/README.md](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md).
The Game of Thrones demo also includes an OpenAI service that generates AI follow-up questions, demonstrating a typical pattern: retrieve memories, build context, call an LLM, and surface follow-ups to the user. Source: [use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/backend/src/services/OpenAIService.ts).
## Benchmarks
EverOS is evaluated against two public benchmarks that target long-context memory and hierarchical retrieval.
**LoCoMo** measures conversational memory over very long dialogues. Community issue #3 notes the published score of **92.3%** on the LoCoMo test set, compared with a prior SOTA in the 84–85% range, and requests per-question detail. Community issue #205 asks whether the answering prompt used during evaluation is the CoT prompt shown in the paper — the project does not document this in the repo, so users reproducing the number must consult the paper directly. Source: [community context #3, #205].
**HyperMem Evaluation Pipeline** runs in stages. Community issue #195 reports that stage 2 took more than four hours to execute, which is a frequent observation; the pipeline is designed for full-corpus sweeps rather than quick smoke tests. If a stage 2 run appears stuck, it is almost always waiting on the LLM calls, not the memory store. Source: [community context #195].
Community issue #56 clarifies that the **2.5K token figure** reported for LoCoMo with `gpt-4o-mini` is the *total* consumption, including both memory generation and the retrieval-grounded answering pass — not just one of the two. Source: [community context #56].
## Security Notes (1.0.1)
The 1.0.1 release tightens path-traversal defenses. `sender_id` now carries the same character whitelist and `.` / `..` rejection as `app_id` and `project_id`, while still permitting `@` and `+` for email-style and plus-addressing identifiers. The `MarkdownWriter` also rejects write targets that fall outside the allowed boundary, giving defense-in-depth containment on file outputs. Source: [community context, 1.0.1 release notes].
## See Also
- [Game of Thrones Demo README](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/game-of-throne-demo/README.md)
- [Claude Code Plugin Ask Command](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/claude-code-plugin/commands/ask.md)
- [Use Cases Catalog](https://github.com/EverMind-AI/EverOS/blob/main/use-cases/README.md)
---
---
## Pitfall Log
Project: EverMind-AI/EverOS
Summary: Found 10 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.
## 1. Installation risk - Installation risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/EverMind-AI/EverOS/issues/299
## 2. Configuration risk - Configuration risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/EverMind-AI/EverOS
## 3. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/EverMind-AI/EverOS/issues/283
## 4. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/EverMind-AI/EverOS
## 5. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/EverMind-AI/EverOS
## 6. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/EverMind-AI/EverOS
## 7. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/EverMind-AI/EverOS
## 8. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/EverMind-AI/EverOS/issues/281
## 9. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/EverMind-AI/EverOS
## 10. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/EverMind-AI/EverOS