diff --git a/README.md b/README.md index 211acbc4..c63c4008 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,262 @@ -# EverOS +
-> Local-first markdown memory framework for AI agents and user chats β€” lightweight, dev-friendly, small-team. +![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) -[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/) +

+ X + HuggingFace + Discord + WeChat +

---- +[Website](https://evermind.ai) Β· [Documentation](https://docs.evermind.ai) Β· [Blog](https://evermind.ai/blogs) Β· [δΈ­ζ–‡](README.zh-CN.md) -## What is EverOS +
-EverOS is an open-source Python framework that turns conversations, agent trajectories, and files into **structured, retrievable, evolving long-term memory** for AI agents and user chats. Designed for **lightweight local deployments** (small teams, individual developers), with three core principles: -1. **Markdown as Source of Truth** β€” All memory persists as plain `.md` files. Open, edit, grep, version with Git, view in Obsidian. No black-box database lock-in. -2. **Lightweight three-piece storage** β€” `Markdown` files (truth) + `SQLite` (state/queue) + `LanceDB` (vector + BM25 + scalar). No MongoDB / Elasticsearch / Milvus / Redis / Kafka required. -3. **EverAlgo as pure algorithm library** β€” Memory extraction algorithms are decoupled into a separate library; this project orchestrates and persists. +
-## Architecture at a glance +
+ Table of Contents +
+ +- [Why Ever OS](#why-ever-os) +- [Quick Start](#quick-start) +- [Use Cases](#use-cases) +- [Documentation](#documentation) +- [Star Us](#star-us) +- [EverMind Ecosystems](#evermind-ecosystems) +- [Contributing](#contributing) + +
+ +
+ + +## Why Ever OS + +EverOS is a Python library and local-first memory runtime for agents and +makers. It gives one portable memory layer across coding assistants, apps, +devices, and workflows from day one. It stores conversations, files, and agent +trajectories as readable Markdown, then syncs local SQLite and LanceDB indexes +for fast retrieval and self-evolving reuse. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TitleEverOSOther Agent Memory Libraries
Markdown source of truthβœ… Canonical .md files that are readable, editable, diffable, and Git-versioned❌ Usually API, vector, graph, dashboard, or database state
Direct file editingβœ… Edit .md files; cascade watcher syncs❌ Usually SDK, API, dashboard, or backend update paths
Local three-part stackβœ… Markdown + SQLite + LanceDB; no MongoDB, Elasticsearch, or Redis required❌ Often depends on managed services, vector DBs, graph DBs, or server stacks
User + agent tracksβœ… User episodes/profile and agent cases/skills are separate first-class surfaces❌ Usually centered on chat history, profiles, entities, facts, or retrieval records
Orthogonal retrievalβœ… Search by user_id, agent_id, app_id, project_id, and session_id❌ Usually app, namespace, tenant, thread, or graph scoped
Knowledge Wikiβœ… Editable, source-backed Markdown knowledge pages with taxonomy, CRUD APIs, and topic search❌ Usually separate from memory, trapped in a dashboard, or not tied back to source files
Reflectionβœ… Offline memory evolution that merges episode clusters and refines profiles and skills between sessions❌ Usually retrieval-only memory with little background consolidation or long-horizon improvement
+ +
+ +## Quick Start + +> Goal: play with the memory visualizer first, then start EverOS, write one +> real memory, and search it back. + +### 0. Prerequisites + +- Python 3.12+ +- No API keys are needed for `everos demo`. +- To run the real server-backed memory flow, create two provider keys before + `everos init`: + +| Capability | Provider | Used for | Fill these `.env` slots | +| --- | --- | --- | --- | +| Chat + multimodal | [OpenRouter](https://openrouter.ai/) | `LLM` / `MULTIMODAL` | `EVEROS_LLM__API_KEY`, `EVEROS_MULTIMODAL__API_KEY` | +| Embedding + rerank | [DeepInfra](https://deepinfra.com/) | `EMBEDDING` / `RERANK` | `EVEROS_EMBEDDING__API_KEY`, `EVEROS_RERANK__API_KEY` | + +You can use other OpenAI-compatible providers by changing the matching +`*__BASE_URL` fields in `.env`. + +### 1. Install + +```bash +uv pip install everos +# or: pip install everos ``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ entrypoints/ (CLI + HTTP API) β”‚ presentation -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ service/ (use cases: memorize/retrieve) β”‚ application -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ memory/ (extract + search + cascade) β”‚ domain -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ infra/ (markdown / sqlite / lancedb) β”‚ infrastructure -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↑ ↑ - component/ core/ - (LLM/Embedding) (observability/lifespan) + +### 2. Play With The Demo + +Run this before configuring API keys or starting the server: + +```bash +everos demo ``` -DDD 5 layers, single-direction dependency. See [docs/architecture.md](docs/architecture.md). +The command asks for one memory and one recall question, then opens a +full-screen terminal UI. This is an educational visualizer: it is hardcoded, +local to the CLI, and does not connect to the EverOS server. Its job is to make +the memory lifecycle visible: conversation -> memory sphere -> recall -> source +proof -> confetti. See [docs/everos-demo.md](docs/everos-demo.md) for the demo +scope and TUI source layout. + +The sphere moves through ingest, extraction, indexing, recall, source reveal, +and a confetti burst after the first memory lands. Press `r` to replay and `q` +to quit. -## Quick start +

+ Animated EverOS demo preview showing the memory sphere moving through recall and confetti states +

-### Install as a package +For the looping showroom view used in README media, run: ```bash -uv pip install everos # or: pip install everos +everos demo --cinematic +``` -# Generate starter config (model defaults bundled inside the wheel) -everos init # writes ~/.everos/everos.toml + ome.toml (use --root to relocate) -# Edit ~/.everos/everos.toml and fill the api_key fields (see comments inside). +If your shell is not interactive, or you want a copyable preview, use: -everos --help +```bash +everos demo --plain +``` + +### 3. Configure + +Generate a starter `.env` file, then fill the four API key slots shown in the +generated comments. With the default setup, paste your OpenRouter key into the +`LLM` / `MULTIMODAL` slots and your DeepInfra key into the `EMBEDDING` / +`RERANK` slots. + +```bash +everos init +# or, from a source checkout: +cp .env.example .env +``` + +`everos init` writes `./.env` by default. Use `everos init --xdg` to +write `${XDG_CONFIG_HOME:-~/.config}/everos/.env` instead. + +### 4. Start EverOS + +```bash everos server start ``` -`everos init` writes two TOML files into the memory root (`~/.everos` by -default; relocate with `--root`): `everos.toml` (app settings + provider -credentials) and `ome.toml` (offline-engine schedules). `everos server start` -reads `/everos.toml` and exits with an error if it is missing. Any -setting can also be overridden by an `EVEROS_*` environment variable -(e.g. `EVEROS_LLM__API_KEY`). The endpoint stack is OpenAI-protocol -compatible (OpenAI / OpenRouter / vLLM / Ollama / DeepInfra …) β€” set the -`base_url` field in each provider section of `everos.toml` to point at any -of them. +Keep the server running, then open a second terminal and check it: + +```bash +curl http://127.0.0.1:8000/health +``` + +Expected response: + +```json +{"status":"ok"} +``` + +`everos server start` searches for `.env` in this order: `--env-file ` β†’ +`./.env` (cwd) β†’ `${XDG_CONFIG_HOME:-~/.config}/everos/.env` β†’ `~/.everos/.env`. +The endpoint stack is OpenAI-protocol compatible (OpenAI / OpenRouter / vLLM / +Ollama / DeepInfra) - override `*__BASE_URL` in the generated `.env` to point +at any of them. + +Now make the demo real. In the second terminal, run: + +```bash +everos demo --live +``` + +Live demo mode connects to the running server and performs the real +`/health` -> `/api/v1/memory/add` -> `/api/v1/memory/flush` -> +`/api/v1/memory/search` flow before opening the same memory sphere UI. Use +`--server-url ` if your server is not on `http://127.0.0.1:8000`. + +### 5. Try Your First Memory + +Add a tiny conversation: + +```bash +TS=$(($(date +%s)*1000)) + +curl -X POST http://127.0.0.1:8000/api/v1/memory/add \ + -H 'Content-Type: application/json' \ + -d "{ + \"session_id\": \"demo-001\", + \"app_id\": \"default\", + \"project_id\": \"default\", + \"messages\": [ + {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $TS, \"content\": \"I love climbing in Yosemite every spring.\"}, + {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+10000)), \"content\": \"My favorite coffee shop is Blue Bottle in SOMA.\"} + ] + }" +``` + +Force extraction for the local demo: + +```bash +curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \ + -H 'Content-Type: application/json' \ + -d '{"session_id":"demo-001","app_id":"default","project_id":"default"}' +``` + +Search it back: + +```bash +curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ + -H 'Content-Type: application/json' \ + -d '{ + "user_id": "alice", + "app_id": "default", + "project_id": "default", + "query": "Where do I like to climb?", + "top_k": 5 + }' +``` + +You should see the Yosemite memory in the response. If the result is empty on +the first try, wait a moment and retry; Markdown is written synchronously, while +the local index catches up in the background. + +> [!TIP] +> **First memory unlocked.** +> You just gave EverOS a fact, flushed it into durable Markdown-backed memory, +> and searched it back through the local index. That is the core loop. +> Want to see the source of truth? Open `~/.everos` and inspect the generated +> Markdown files. -#### Multi-modal (optional) +For annotated responses and the Markdown files EverOS creates, see +[QUICKSTART.md](QUICKSTART.md). + +### Optional: Ingest Multimodal Files To ingest non-text content (image / pdf / audio / office documents) through `/api/v1/memory/add` `content` items, install the optional @@ -71,15 +268,14 @@ uv pip install 'everos[multimodal]' # or: pip install 'everos[multimodal]' This pulls in `everalgo-parser` (with the `[svg]` bundle for SVG support via cairosvg) and wires up the multimodal LLM client -(the `[multimodal]` section in `everos.toml`, defaults to -`google/gemini-3-flash-preview`). +(`EVEROS_MULTIMODAL__*` fields in `.env`, defaults to +`google/gemini-3-flash-preview` via OpenRouter). **Office document support requires LibreOffice as a system dependency.** The parser shells out to `soffice` (LibreOffice's headless renderer) to convert `.doc` / `.docx` / `.ppt` / `.pptx` / `.xls` / `.xlsx` to PDF before feeding the result into the multimodal LLM. Without LibreOffice, -office uploads return HTTP 503 (`CAPABILITY_UNAVAILABLE`) with a clear -error message; PDF / image +office uploads return HTTP 415 with a clear error message; PDF / image / audio / HTML / email parsing is unaffected. Install on the host before serving office documents: @@ -89,108 +285,479 @@ brew install --cask libreoffice # macOS sudo apt-get install -y libreoffice # Debian / Ubuntu ``` -For the full multimodal contract (supported modalities, `uri` vs -`base64`, config, error semantics, end-to-end curl examples), see -[docs/multimodal.md](docs/multimodal.md). - -For a step-by-step walkthrough (add a conversation β†’ flush β†’ search β†’ -read the markdown), see [QUICKSTART.md](QUICKSTART.md). - -### Develop locally +### For Contributors ```bash git clone https://github.com/EverMind-AI/EverOS.git cd EverOS uv sync # creates ./.venv and installs deps -source .venv/bin/activate # β€” or skip activation and prefix every command with `uv run` -everos init # fill in the [llm] api_key in the generated everos.toml +source .venv/bin/activate # or prefix commands with `uv run` +everos demo --plain # try the local educational demo; no API keys needed +everos init # paste OpenRouter + DeepInfra keys into .env everos --help make test ``` -## Storage layout +
+
-``` -~/.everos/ -β”œβ”€β”€ default_app/ # app_id ("default" β†’ "default_app" on disk) -β”‚ └── default_project/ # project_id ("default" β†’ "default_project") -β”‚ β”œβ”€β”€ users// -β”‚ β”‚ β”œβ”€β”€ user.md # profile -β”‚ β”‚ β”œβ”€β”€ episodes/ # daily-log episodes (visible) -β”‚ β”‚ β”œβ”€β”€ .atomic_facts/ # nested facts (dotfile-hidden) -β”‚ β”‚ └── .foresights/ # predictive memory (dotfile-hidden) -β”‚ └── agents// -β”‚ β”œβ”€β”€ agent.md -β”‚ β”œβ”€β”€ .cases/ # one task case per entry -β”‚ └── skills/ # named procedural memories -β”œβ”€β”€ .index/ # derived indexes (rebuildable from md) -β”‚ β”œβ”€β”€ sqlite/system.db # state + queue + audit -β”‚ └── lancedb/*.lance/ # vector + BM25 + scalar -└── .tmp/ # transient working files -``` +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) -Open any `//users//` folder in Obsidian β€” your -agent's brain is just files. The dotfile directories (`.atomic_facts/`, -`.foresights/`, `.cases/`) stay hidden by default so the visible folder -is the user-facing memory surface, while extracted derivatives sit -quietly alongside. +
-## Features +## Use Cases -- **Hybrid retrieval**: BM25 + vector (HNSW/IVF-PQ) + scalar filter, single-query in LanceDB -- **Cascade index sync**: edit a `.md` β†’ file watcher β†’ entry-level diff β†’ LanceDB sync, sub-second -- **Multi-source extraction**: conversations / agent trajectories / file knowledge -- **Dual-track memory**: user-track (Episodes / Profiles) + agent-track (Cases / Skills) -- **Async-first**: full asyncio, single event loop -- **Multi-modal**: text + small image / audio inline; large media via S3/OSS reference +Now that you have had your first successful EverOS moment, explore what people +are building with persistent memory across agents, apps, and community +integrations. -## Project structure +Use cases show what persistent memory makes possible in real products and +workflows. Some examples are packaged in this repository; others point to +external demos or integrations you can study and adapt. -``` -everos/ # repo root -β”œβ”€β”€ src/everos/ # main package (src layout) -β”‚ β”œβ”€β”€ entrypoints/ # cli + api -β”‚ β”œβ”€β”€ service/ # use case orchestration -β”‚ β”œβ”€β”€ memory/ # domain: extract + search + cascade + prompt_slots -β”‚ β”œβ”€β”€ infra/ # storage: markdown + lancedb + sqlite -β”‚ β”œβ”€β”€ component/ # cross-cutting: llm / embedding / config / utils -β”‚ β”œβ”€β”€ core/ # runtime: observability / lifespan / context -β”‚ └── config/ # configuration data + Settings schema -β”œβ”€β”€ tests/ # unit / integration / golden / fixtures -β”œβ”€β”€ docs/ # design docs -└── .claude/ # team-shared rules + skills (auto-loaded by Claude Code) -``` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ +[![banner-gif](https://github.com/user-attachments/assets/840470d7-a838-4c05-8685-dd797d4e9cdf)](https://evermind.ai/usecase_reunite) + +#### Reunite - Find With EverOS + +Parents describe what they remember. Children describe what they recall. Reunite uses semantic memory to surface the connections. + +[Learn more](https://evermind.ai/usecase_reunite) + + + +[![banner-gif](https://github.com/user-attachments/assets/7282b38b-56bf-4356-aa7b-06a845e7683d)](https://github.com/tt-a1i/hive) + +#### Hive Orchestrator + +Browser-native hive-mind for CLI coding agents - Claude Code, Codex, Gemini, and OpenCode collaborate as real PTY processes via a team protocol. + +[Code](https://github.com/tt-a1i/hive) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/867d9329-ce9a-496f-ab1e-15c77974e5fa)](https://github.com/tt-a1i/evermemos-mcp) + +#### AI Coding Assistants With EverOS + +Universal long-term memory layer for AI coding assistants, powered by EverOS. + +[Code](https://github.com/tt-a1i/evermemos-mcp) + + + +[![banner-gif](https://github.com/user-attachments/assets/a4f0fd86-1c81-4445-bebc-e51eb5e33b30)](https://github.com/yuansui123/AI-Data-Technician-EverMemOS) + +#### AI Data Technician + +An agentic AI system that learns from scientist interaction to inspect, analyze, and classify high-dimensional time series data - with persistent memory that improves across sessions. + +[Code](https://github.com/yuansui123/AI-Data-Technician-EverMemOS) + +
+ +![banner-gif](https://github.com/user-attachments/assets/650b901b-c9ba-4001-bac7-626b009df830) + +#### Rokid AI Assistant With EverOS + +Connect to EverOS within Rokid Glasses enabling long-term memory for all of your smart activities. + +Coming soon + + + +![banner-gif](https://github.com/user-attachments/assets/85b338b2-e48e-4a65-9f30-0bc6998df872) + +#### Creative Assistant With Memory + +Creative assistant with long-term memory, so your creative context stays available across sessions. + +Coming soon + +
+Back to top +
+ +[![banner-gif](https://github.com/user-attachments/assets/f30617a1-adc0-4271-bc0e-c3a0b28cb903)](https://github.com/xunyud/Earth-Online) + +#### Earth Online Memory Game + +Earth Online is a memory-aware productivity game that turns everyday planning into a living quest log. + +[Code](https://github.com/xunyud/Earth-Online) + + + +[![banner-gif](https://github.com/user-attachments/assets/57d8cda7-35a5-4561-b794-5520dffc917b)](https://github.com/golutra/golutra) + +#### Multi-Agent Orchestration Platform + +Golutra presents a multi-agent workforce for engineering teams, extending the IDE model from a single assistant to coordinated agents. + +[Code](https://github.com/golutra/golutra) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/75f19db5-30f6-4eed-9b1e-c9c6a0e6b7de)](https://github.com/Yangtze-Seventh/taste-verse) + +#### Your Personal Tasting Universe + +Record, visualize, and explore your tasting journey through an immersive 3D star map. + +[Code](https://github.com/Yangtze-Seventh/taste-verse) + + + +[![banner-gif](https://github.com/user-attachments/assets/93ac2a68-4f18-4fcb-8d87-80aeb00a9d7c)](https://github.com/kellyvv/OpenHer) + +#### EverOS Open Her + +Build AI that feels. Open-source persona engine - personality emerges from neural drives, not prompts. Inspired by Her. + +[Code](https://github.com/kellyvv/OpenHer) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/550071c1-dc39-4964-9f67-ffdfad792345)](https://chromewebstore.google.com/detail/ruminer-browser-agent/lbccjohfpdpimbhpckljimgolndfmfif) + +#### Browser Agent For Personal Memory + +Ruminer brings persistent memory to a browser agent so it can carry personal context across web tasks. + +[Plugin](https://chromewebstore.google.com/detail/ruminer-browser-agent/lbccjohfpdpimbhpckljimgolndfmfif) + + + +[![banner-gif](https://github.com/user-attachments/assets/c258a6c4-fe70-497a-98d1-3dade4a932f6)](https://github.com/nanxingw/EverMem) + +#### EverMem Sync With EverOS + +One command to connect any AI coding CLI to EverMemOS long-term memory. + +[Code](https://github.com/nanxingw/EverMem) + +
+Back to top +
+ +[![banner-gif](https://github.com/user-attachments/assets/39274473-ceb3-48fb-a031-e22230decbe2)](https://github.com/mco-org/mco) + +#### MCO - Orchestrate AI Coding Agents + +MCO equips your primary agent with an agent team that can work together to solve complex tasks. + +[Code](https://github.com/mco-org/mco) + + + +[![banner-gif](https://github.com/user-attachments/assets/314c9126-8e08-4688-bbbb-8555ad58cf67)](https://github.com/onenewborn/StudyBuddy-public) + +#### Study Buddy With Self-Evolving Memory + +Study proactively with an agent that has self-evolving memory. + +[Code](https://github.com/onenewborn/StudyBuddy-public) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/21da76aa-9a8b-48e0-9134-42429d7390e7)](https://github.com/TonyLiangDesign/MemoCare) + +#### Alzheimer's Memory Assistant + +Empowering individuals with advanced memory support and daily assistance. + +[Code](https://github.com/TonyLiangDesign/MemoCare) + + + +[![banner-gif](https://github.com/user-attachments/assets/e2428df3-ea11-4e88-8f9c-dad437dd8998)](https://github.com/AlexL1024/NeuralConnect) + +#### Memory-Driven Multi-Agent NPC Experience + +An iOS sci-fi mystery game where players explore and uncover the truth. + +[Code](https://github.com/AlexL1024/NeuralConnect) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/e6eaf308-a874-483f-8874-6934bf95a78f)](https://github.com/elontusk5219-prog/Mobi) + +#### Mobi Companion + +An iOS app where users create, nurture, and live with a personalized AI companion called Mobi. + +[Code](https://github.com/elontusk5219-prog/Mobi) + + + +[![banner-gif](https://github.com/user-attachments/assets/9aabcaa9-f97a-49d2-9109-0b5bb696ed41)](https://github.com/JaMesLiMers/EvermemCompetition-Spiro) + +#### AI Wearable With Memory + +A context-native AI wearable that listens to everyday life and converts conversations into memory. + +[Code](https://github.com/JaMesLiMers/EvermemCompetition-Spiro) + +
+Back to top +
+ +[![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc)](docs/migration-to-1.0.0.md) + +#### Legacy OpenClaw Agent Memory + +Archived pre-1.0.0 plugin reference. New integrations should use the current EverOS API. + +[Learn more](docs/migration-to-1.0.0.md) + + + +[![banner-gif](https://github.com/user-attachments/assets/3a2357a1-c0c3-464a-8979-0d1cdfc9b0d4)](https://github.com/TEN-framework/ten-framework/tree/04cb80601374fa9e35b4e544b2dbd23286ca7763/ai_agents/agents/examples/voice-assistant-with-EverMemOS) + +#### Live2D Character With Memory + +Add long-term memory to a real-time Live2D character, powered by [TEN Framework](https://github.com/TEN-framework/ten-framework). + +[Code](https://github.com/TEN-framework/ten-framework/tree/04cb80601374fa9e35b4e544b2dbd23286ca7763/ai_agents/agents/examples/voice-assistant-with-EverMemOS) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/c36bdc04-97d3-4fe9-97d9-4b93b475595a)](https://screenshot-analysis-vercel.vercel.app/) + +#### Computer-Use With Memory + +Run screenshot-based analysis with computer-use and store the results in memory. + +[Live Demo](https://screenshot-analysis-vercel.vercel.app/) + + + +[![banner-gif](https://github.com/user-attachments/assets/54a7cf8f-62c4-4fbc-9d50-b214d034e051)](use-cases/game-of-throne-demo) + +#### Game Of Thrones Memories + +A demonstration of AI memory infrastructure through an interactive Q&A experience with *A Game of Thrones*. + +[Code](use-cases/game-of-throne-demo) + +
+ +[![banner-gif](https://github.com/user-attachments/assets/af37c1f6-7ba5-430c-b99d-2a7e7eac618f)](use-cases/claude-code-plugin) + +#### Claude Code Plugin + +Persistent memory for Claude Code. Automatically saves and recalls context from past coding sessions. + +[Code](use-cases/claude-code-plugin) + + + +[![banner-gif](https://github.com/user-attachments/assets/d521d28c-0ccd-44ff-aecc-828245e2f973)](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html) + +#### Memory Graph Visualization + +Explore stored entities and relationships in a graph interface. Frontend demo; backend integration is in progress. + +[Live Demo](https://main.d2j21qxnymu6wl.amplifyapp.com/graph.html) + +
+ +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
## Documentation -- [docs/overview.md](docs/overview.md) β€” Project overview & vision -- [docs/architecture.md](docs/architecture.md) β€” DDD layered architecture & dependency rules -- [docs/engineering.md](docs/engineering.md) β€” Engineering & dev-efficiency infrastructure (CI / tooling / Claude Code) -- [docs/multimodal.md](docs/multimodal.md) β€” Multimodal memory: ingest image / pdf / audio / office docs via the HTTP API +- [docs/everos-demo.md](docs/everos-demo.md) β€” Demo scope and TUI source layout +- [docs/how-memory-works.md](docs/how-memory-works.md) β€” Markdown, SQLite, LanceDB, and recall flow +- [docs/use-cases.md](docs/use-cases.md) β€” Full use-case gallery and integration examples +- [docs/engineering.md](docs/engineering.md) β€” Engineering and CI tooling +- [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) β€” Legacy API migration notes - [CHANGELOG.md](CHANGELOG.md) β€” Release notes - [CONTRIBUTING.md](CONTRIBUTING.md) β€” How to contribute -- [.claude/rules/](.claude/rules/) β€” Detailed coding conventions (auto-loaded by Claude Code) -## Use Cases +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ +## Star Us + +If EverOS is useful to your agent stack, please star the repo. It helps more +builders discover the project and gives the memory ecosystem a stronger signal +to keep improving. + +### Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=EverMind-AI/EverOS&type=Date)](https://www.star-history.com/#EverMind-AI/EverOS&Date) + +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
-See [use-cases/README.md](use-cases/README.md) for the full gallery. +## EverMind Ecosystems + +EverMind is an open-source ecosystem for long-term memory, self-evolving agents, and memory evaluation. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EverMind Open-Source Ecosystem
Memory RuntimeEverOS - the local memory operating system and research-backed runtime for agent and user memory.
Algorithm EngineEverAlgo - stateless extraction, ranking, parsing, and memory operators that power EverOS.
Hypergraph MemoryHyperMem - hypergraph memory for long-term conversations, with its own benchmark-backed topic -> episode -> fact retrieval method.
BenchmarksEverMemBench Β· EvoAgentBench - evaluation suites for conversational memory and agent self-evolution.
Long-Context ResearchMSA - Memory Sparse Attention for scalable latent memory and 100M-token contexts.
Personal Memory LayerEverMe - CLI and agent plugin suite for cross-device, cross-agent personal memory.
Developer Integrationsevermem-claude-code Β· everos-plugins - plugins, skills, and migration tooling for AI coding agents.
-## Status +Together, these repositories form EverMind's research-to-runtime stack: new memory methods, reusable algorithms, benchmark evidence, and practical agent integrations. + +
+
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) + +
+ +
+ +## Contributing + +Contributions are welcome across the whole repository: memory methods, benchmark coverage, use-case examples, documentation, and bug fixes. Browse [Issues](https://github.com/EverMind-AI/EverOS/issues) to find a good entry point, then open a PR when you are ready. -**Stable (v1.1.0)** β€” Released on PyPI; the v1 API is stable. +
-## License +> [!TIP] +> +> **Welcome all kinds of contributions** πŸŽ‰ +> +> Help make EverOS better. Code, documentation, benchmark reports, use-case write-ups, and integration examples are all valuable. Share your projects on social media to inspire others. +> +> Connect with one of the EverOS maintainers [@elliotchen200](https://x.com/elliotchen200) on 𝕏 or [@cyfyifanchen](https://github.com/cyfyifanchen) on GitHub for project updates, discussions, and collaboration opportunities. + +![divider](https://github.com/user-attachments/assets/2e2bbcc6-e6d8-4227-83c6-0620fc96f761#gh-light-mode-only) +![divider](https://github.com/user-attachments/assets/d57fad08-4f49-4a1c-bdfc-f659a5d86150#gh-dark-mode-only) + +### Code Contributors + +[![EverOS Contributors](https://contrib.rocks/image?repo=EverMind-AI/EverOS)](https://github.com/EverMind-AI/EverOS/graphs/contributors) + +![divider](https://github.com/user-attachments/assets/2e2bbcc6-e6d8-4227-83c6-0620fc96f761#gh-light-mode-only) +![divider](https://github.com/user-attachments/assets/d57fad08-4f49-4a1c-bdfc-f659a5d86150#gh-dark-mode-only) + +### License [Apache License 2.0](LICENSE) β€” see [NOTICE](NOTICE) for third-party attributions. -## Citation +### Citation If you use EverOS in research, see [CITATION.md](CITATION.md). ---- +
+ +
+ +[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top) -**Acknowledgments**: This project builds on prior research and tooling β€” see [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md). +