diff --git a/QUICKSTART.md b/QUICKSTART.md index 9afe547..52e5216 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,298 +1,276 @@ # Quickstart -> Five minutes from zero to "I added a conversation, queried it back, and -> can read it as plain Markdown." +> Five minutes from one OpenRouter API key to durable Markdown memory and +> keyword recall. -EverOS runs as a **service** — start the server, then call the HTTP API. -There is no in-process library mode; an `everos` server is always in -front of your agent. +EverOS runs as a local service. The minimum production path needs only an LLM: +configure one OpenRouter key, start the server, then call the HTTP API. + +## What the one-key setup includes + +With only `[llm]` configured, EverOS can: + +- start the server; +- extract conversations into durable Markdown; +- keep the local index in sync; and +- retrieve memories with keyword search. + +Embedding, rerank, knowledge, and multimodal providers are optional upgrades. +They are not required for this walkthrough. ## Prerequisites -- **Python 3.12+** -- **API keys** for three capabilities: a chat LLM (memory extraction), - an embedding model (vector retrieval), and a reranker. Any - OpenAI-compatible endpoint works. +- Python 3.12+ +- One [OpenRouter API key](https://openrouter.ai/keys) ## 1. Install -**From PyPI** (users): +From PyPI: ```bash pip install everos -# or: uv pip install everos +# or: uv pip install everos ``` -**From source** (contributors / developers): +From source: ```bash git clone https://github.com/EverMind-AI/EverOS.git cd EverOS -uv sync # install all deps into .venv +uv sync +source .venv/bin/activate ``` -> **Note:** source install creates a `.venv` virtualenv. Subsequent -> `everos` commands need either `uv run everos ...` or activate the venv -> first (`source .venv/bin/activate`). +You can also prefix source-checkout commands with `uv run` instead of +activating the virtual environment. -## 2. Configure +## 2. Try the standalone demo — no key required + +Before initialization or provider setup, run: ```bash -everos init # default root: ~/.everos -everos init --root /data/everos # or specify a custom root +everos demo ``` -> **Root directory** — defaults to `~/.everos`. Use `--root ` to -> relocate; all subsequent commands (`server start`, `cascade status`, -> etc.) must use the matching `--root`. Any setting in `everos.toml` can -> also be overridden via `EVEROS_*` environment variables for containers -> and CI. +The command asks for one memory and one recall question, then opens a local +terminal visualizer. It is hardcoded and completely decoupled from the real +workflow: it needs no API key, does not start or call the EverOS server, and +does not write to your real memory root. -This creates `everos.toml` and `ome.toml` under the root directory. -Open `everos.toml` and fill in three sections — here's the minimum -viable config: +Press `r` to replay and `q` to quit. For a copyable non-interactive preview: + +```bash +everos demo --plain +``` + +See [docs/everos-demo.md](docs/everos-demo.md) for the visualizer's scope. + +## 3. Initialize EverOS + +```bash +everos init +``` + +This creates two files under the default memory root: + +```text +~/.everos/ +├── everos.toml # provider and server configuration +└── ome.toml # memory strategy configuration +``` + +To use another root, run `everos init --root ` and pass the same +`--root ` to subsequent commands. + +## 4. Add your OpenRouter key + +Open `~/.everos/everos.toml`. The generated +`[llm]` section already contains the recommended model and base URL; replace +only the empty `api_key`: ```toml [llm] -model = "gpt-4.1-mini" # or your preferred model -base_url = "https://openrouter.ai/api/v1" # any OpenAI-compatible endpoint -api_key = "sk-..." # your API key - -[embedding] -model = "Qwen/Qwen3-Embedding-4B" -base_url = "https://api.deepinfra.com/v1/openai" -api_key = "..." - -[rerank] -provider = "deepinfra" -model = "Qwen/Qwen3-Reranker-4B" -base_url = "https://api.deepinfra.com/v1/inference" -api_key = "..." +model = "openai/gpt-4.1-mini" +api_key = "" +base_url = "https://openrouter.ai/api/v1" ``` -The generated file pre-fills recommended `model` and `base_url` -defaults — just drop in your API keys. Any OpenAI-compatible endpoint -works. +Leave `[embedding]`, `[rerank]`, and `[multimodal]` unchanged for this +walkthrough. Their empty keys do not prevent the server from starting; this +setup uses keyword search. -> **Multimodal** (`[multimodal]`) is optional — only needed when -> ingesting image / pdf / audio content items. See -> [docs/multimodal.md](docs/multimodal.md) for setup. - - -## 3. Start the server - -Check your file descriptor limit — EverOS opens many LanceDB segment -files under concurrent search + indexing. Platform defaults: -**macOS 256** · **Linux 1024** · **Windows 8192**. If yours is below -4096, raise it before starting: - -Run these in the **same terminal** where you will start the server — -`ulimit` is per-shell-session, not global: +## 5. Start the server ```bash -ulimit -n # check current limit -ulimit -n 4096 # raise if needed -everos server start [--root ] # must be in the same session +everos server start ``` -> **No side effects** — `ulimit -n` only raises the per-process ceiling. -> It does not pre-allocate memory or file handles, and has zero -> performance cost. For Linux production, set `LimitNOFILE=65536` in -> your systemd unit file. - -You should see: - -``` -starting everos on 127.0.0.1:8000 -INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) -``` - -The server runs in the foreground. **Open a second terminal** for the -steps below. - -Verify it's up: +The server runs in the foreground on `http://127.0.0.1:8000`. Open a second +terminal and verify it: ```bash curl http://127.0.0.1:8000/health -# {"status":"ok"} ``` -## 4. Add a conversation - -Send messages to the server — one at a time or in batches. Each batch -belongs to a `session_id`, which represents one conversation thread. -Timestamps are Unix epoch in **milliseconds** (UTC). - -> [!NOTE] -> Business endpoints live under `/api/v2`. The older `/api/v1` prefix still -> resolves to the same handlers so existing integrations keep working, but it -> is a legacy alias that may be removed in a future major release — write new -> code against `/api/v2`. - -First, a chat about climbing: - -```bash -TS=$(($(date +%s)*1000)) -curl -X POST http://127.0.0.1:8000/api/v2/memory/add \ - -H 'Content-Type: application/json' \ - -d "{ - \"session_id\": \"demo-001\", - \"messages\": [ - {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $TS, \"content\": \"I just got back from a week in Yosemite. The climbing was incredible.\"}, - {\"sender_id\": \"agent1\", \"role\": \"assistant\", \"timestamp\": $((TS+10000)), \"content\": \"That sounds amazing! Which routes did you do?\"}, - {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+20000)), \"content\": \"Mostly cracks on El Cap. I go every spring — it's my favorite season there.\"} - ] - }" -# → status: "accumulated" -``` - -Now the topic shifts to work: - -```bash -curl -X POST http://127.0.0.1:8000/api/v2/memory/add \ - -H 'Content-Type: application/json' \ - -d "{ - \"session_id\": \"demo-001\", - \"messages\": [ - {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+60000)), \"content\": \"By the way, I switched to biking to work last month. Loving it so far.\"}, - {\"sender_id\": \"agent1\", \"role\": \"assistant\", \"timestamp\": $((TS+70000)), \"content\": \"How long is your commute?\"}, - {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+80000)), \"content\": \"About 25 minutes. I stop at Blue Bottle in SOMA for coffee most mornings.\"} - ] - }" -``` - -Response: +The response includes the complete capability matrix. In the one-key setup, +the important fields look like this: ```json { - "data": { - "message_count": 3, - "status": "extracted" - } + "status": "ok", + "capabilities": { + "llm": true, + "embed": false, + "rerank": false + }, + "disabled_features": [ + "vector_search", + "hybrid_search", + "agentic_search", + "reflection", + "skill_extraction", + "knowledge" + ] } ``` -EverOS detected a topic shift (climbing → commute) and automatically -extracted the earlier conversation into memory. +The actual response also includes version, multimodal/parser capabilities, and +cascade readiness. -The `status` field tells you what happened: +> [!NOTE] +> EverOS opens local index files during concurrent search and indexing. If you +> encounter file-descriptor errors, run `ulimit -n 4096` in the same shell +> before starting the server. -| Status | Meaning | -|---|---| -| `accumulated` | Messages buffered, still part of the same topic. | -| `extracted` | Topic shift detected — memory extracted from the buffer. | +## 6. Add a conversation -> For the full API contract, see [docs/openapi.json](docs/openapi.json). +Business endpoints live under `/api/v2`. The `/api/v1` prefix remains a legacy +compatibility alias, but new integrations should use `/api/v2`. -## 5. Flush (manual extraction) +Timestamps are Unix epoch milliseconds in UTC: -If you want to extract memory without waiting for a topic shift — for -example at the end of a session — call `/flush`: +```bash +TS=$(($(date +%s)*1000)) + +curl -X POST http://127.0.0.1:8000/api/v2/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\": \"agent1\", \"role\": \"assistant\", \"timestamp\": $((TS+10000)), \"content\": \"Which routes do you enjoy most?\"}, + {\"sender_id\": \"alice\", \"role\": \"user\", \"timestamp\": $((TS+20000)), \"content\": \"Mostly the cracks on El Cap.\"} + ] + }" +``` + +Messages are buffered by session until EverOS detects a boundary or the client +explicitly flushes the session. + +## 7. Flush at the end of the session ```bash curl -X POST http://127.0.0.1:8000/api/v2/memory/flush \ -H 'Content-Type: application/json' \ - -d '{"session_id":"demo-001"}' + -d '{ + "session_id": "demo-001", + "app_id": "default", + "project_id": "default" + }' ``` -```json -{ - "data": { - "status": "extracted" - } -} -``` +A successful flush returns `data.status` as `"extracted"`. The extraction is +written to Markdown, then the cascade worker projects it into the local index. -This forces extraction of whatever is still in the buffer. - -## 6. Search +## 8. Search with the one-key method ```bash curl -X POST http://127.0.0.1:8000/api/v2/memory/search \ -H 'Content-Type: application/json' \ -d '{ "user_id": "alice", - "query": "Where do I like to climb?", + "app_id": "default", + "project_id": "default", + "query": "Where does Alice like to climb?", + "method": "keyword", "top_k": 5 }' ``` -Response (trimmed): +The response should contain an episode whose summary mentions Yosemite or El +Cap. If the first search is empty, wait a moment for cascade indexing and retry. -```json -{ - "data": { - "episodes": [ - { - "id": "alice_ep_20260528_00000002", - "summary": "... Alice shared that she loves climbing in Yosemite every spring ...", - "score": 0.628, - "atomic_facts": [ - { - "content": "Alice said she loves climbing in Yosemite every spring.", - "score": 0.628 - } - ] - } - ] - } -} -``` +> [!IMPORTANT] +> Keep `"method": "keyword"` when only the LLM is configured. The API default +> is hybrid, which requires embedding and returns HTTP 422 in the one-key tier. -Hybrid retrieval (BM25 + vector + scalar) returns the matching episode -with its atomic facts nested under it. +Keyword retrieval returns matching episodes from the local BM25 index. Atomic +facts are created by an embedding-dependent strategy, so they are not expected +in the OpenRouter Tier 1 response. -## 7. Your memory is just Markdown +## 9. Read the Markdown source of truth -This is what makes EverOS different — memory persists as plain Markdown: +Your extracted memory is a normal Markdown file under the memory root: -``` -/ ← ~/.everos or your --root path -├── default_app/ ← app_id ("default" → "default_app") -│ └── default_project/ ← project_id ("default" → "default_project") -│ ├── users// -│ │ ├── user.md ← profile -│ │ ├── episodes/ ← daily-log episodes -│ │ ├── .atomic_facts/ ← nested facts (dot-hidden) -│ │ └── .foresights/ ← predictive memory (dot-hidden) +```text +~/.everos/ +├── default_app/ +│ └── default_project/ +│ ├── users/alice/ +│ │ ├── user.md +│ │ ├── episodes/ +│ │ ├── .atomic_facts/ +│ │ └── .foresights/ │ ├── agents// │ │ ├── agent.md -│ │ ├── .cases/ ← task cases -│ │ └── skills/ ← procedural memories -│ └── knowledge/ ← shared knowledge base -├── everos.toml ← provider config -├── ome.toml ← strategy config (hot-reloaded) -├── .index/ ← derived indexes (rebuildable from md) -│ ├── sqlite/system.db -│ └── lancedb/ -└── .tmp/ +│ │ ├── .cases/ +│ │ └── skills/ +│ └── knowledge/ +├── everos.toml +├── ome.toml +└── .index/ + ├── sqlite/system.db + └── lancedb/ ``` -Every memory entry is a plain Markdown file you can directly read and -edit — no database driver needed. +Markdown is canonical; SQLite and LanceDB are derived indexes. You can read, +edit, diff, and version the memory files without a database client. -## Stopping the server +## Upgrade capabilities when you need them -`Ctrl+C` in the server terminal. +The generated `everos.toml` already includes commented guidance and default +models for the optional providers. + +| Configuration | Available capabilities | +| --- | --- | +| `[llm]` only | Add, flush, Markdown persistence, cascade sync, keyword search | +| Add `[embedding]` | Vector/user hybrid search, reflection, skill extraction | +| Add `[rerank]` too | Agentic search, default agent hybrid search, Knowledge Wiki | +| Add `[multimodal]` and install `everos[multimodal]` | Image, PDF, audio, and office-file ingestion | + +EverOS reports unavailable features through `/health`. Requests that require a +missing provider fail fast with a descriptive HTTP 422 instead of silently +degrading to a different search method. + +You can replace OpenRouter with another OpenAI-compatible LLM endpoint by +changing the `[llm]` model, base URL, and key. + +## Stop the server + +Press `Ctrl+C` in the server terminal. ## Next steps -- **Integrate into your agent** — wrap `/add`, `/flush`, `/search` in a - thin HTTP client and call them from your agent loop. -- **App + project scope** — pass `app_id` / `project_id` in your API - requests to partition memory spaces inside one server (defaults to - `"default"` when omitted). -- **Knowledge base** — upload documents via - `/api/v2/knowledge/documents` and search with hybrid retrieval. See - [docs/knowledge.md](docs/knowledge.md). -- **Reflection** — offline memory consolidation; enable in `ome.toml`. - See [docs/reflection.md](docs/reflection.md). -- **Multimodal** — ingest image / pdf / audio / office documents. See - [docs/multimodal.md](docs/multimodal.md). -- **Search modes** — four methods (`HYBRID` / `KEYWORD` / `VECTOR` / - `AGENTIC`) with a filter DSL. See [docs/openapi.json](docs/openapi.json) - for the full API schema. -- **Architecture** — [docs/architecture.md](docs/architecture.md) for - DDD layering; [docs/storage_layout.md](docs/storage_layout.md) for - on-disk layout. -- **Found a bug?** — [open an issue](CONTRIBUTING.md). +- Integrate `/add`, `/flush`, and `/search` into your agent loop. +- Partition memory with `app_id` and `project_id`. +- Explore the full API contract in [docs/openapi.json](docs/openapi.json). +- Configure advanced retrieval in the generated `everos.toml`. +- Run `everos demo --live` after starting a server with embedding configured; + unlike the standalone demo in step 2, live mode calls the real API and uses + hybrid search. +- Read [docs/architecture.md](docs/architecture.md) and + [docs/storage_layout.md](docs/storage_layout.md). +- Set up multimodal ingestion with [docs/multimodal.md](docs/multimodal.md). +- Report problems through [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/README.md b/README.md index 388a9f2..14dc1e4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2) +![EverOS banner](https://github.com/user-attachments/assets/806e9d7f-c861-4b89-9141-11e38f8753e3)

X @@ -88,23 +88,13 @@ for fast retrieval and self-evolving reuse. ## Quick Start -> Goal: play with the memory visualizer first, then start EverOS, write one -> real memory, and search it back. +> One OpenRouter API key is enough to start EverOS, write durable memories, +> and retrieve them with keyword search. -### 0. Prerequisites +### 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`. +- One [OpenRouter API key](https://openrouter.ai/keys) ### 1. Install @@ -113,56 +103,50 @@ uv pip install everos # or: pip install everos ``` -### 2. Play With The Demo +### 2. Try the standalone demo — no key required -Run this before configuring API keys or starting the server: +Before configuring a provider or starting the server, run: ```bash everos demo ``` 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. +full-screen terminal visualizer. It is hardcoded and local to the CLI: it does +not need an API key, start or call the EverOS server, or change anything in the +real memory workflow below.

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

-For the looping showroom view used in README media, run: +Press `r` to replay and `q` to quit. For a non-interactive preview, use +`everos demo --plain`; for the looping showroom view, use +`everos demo --cinematic`. See [docs/everos-demo.md](docs/everos-demo.md) for +the visualizer's scope. -```bash -everos demo --cinematic -``` - -If your shell is not interactive, or you want a copyable preview, use: - -```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. +### 3. Initialize and add your OpenRouter key ```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. +This creates `~/.everos/everos.toml` and `~/.everos/ome.toml`. Open +`~/.everos/everos.toml`; the generated model and OpenRouter URL are already +correct, so replace only the empty `api_key`: + +```toml +[llm] +model = "openai/gpt-4.1-mini" +api_key = "" +base_url = "https://openrouter.ai/api/v1" +``` + +This is the smallest Tier 1 setup: memory add, flush, Markdown persistence, +cascade indexing, and keyword search. + +Use `everos init --root ` if you want a different memory root. Pass the +same `--root ` to subsequent commands. ### 4. Start EverOS @@ -176,30 +160,10 @@ Keep the server running, then open a second terminal and check it: curl http://127.0.0.1:8000/health ``` -Expected response: +Look for `"status":"ok"`. With this one-key setup, `capabilities.llm` is +`true`; embedding and rerank remain `false` until you configure them. -```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/v2/memory/add` -> `/api/v2/memory/flush` -> -`/api/v2/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 +### 5. Add and retrieve your first memory > [!NOTE] > Business endpoints live under `/api/v2`. The older `/api/v1` prefix still @@ -225,7 +189,7 @@ curl -X POST http://127.0.0.1:8000/api/v2/memory/add \ }" ``` -Force extraction for the local demo: +Flush the memory at the end of the session: ```bash curl -X POST http://127.0.0.1:8000/api/v2/memory/flush \ @@ -243,13 +207,14 @@ curl -X POST http://127.0.0.1:8000/api/v2/memory/search \ "app_id": "default", "project_id": "default", "query": "Where do I like to climb?", + "method": "keyword", "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. +You should see the Yosemite memory in the response. Keep +`"method": "keyword"` in this one-key setup because the API defaults to hybrid +search, which requires an embedding provider. > [!TIP] > **First memory unlocked.** @@ -261,6 +226,27 @@ the local index catches up in the background. For annotated responses and the Markdown files EverOS creates, see [QUICKSTART.md](QUICKSTART.md). +### What works with one key? + +The OpenRouter one-key setup is EverOS Tier 1. It supports server startup, +memory add and flush, durable Markdown storage, cascade indexing, and keyword +search. Add optional providers only when you need the features below: + +| Configuration | Adds | +| --- | --- | +| `[llm]` only | Core memory flow and keyword search | +| Add `[embedding]` | Vector/user hybrid search, reflection, and skill extraction | +| Add `[rerank]` too | Agentic search, default agent hybrid search, and Knowledge Wiki | +| Add `[multimodal]` and parser extra | Image, PDF, audio, and office-file ingestion | + +Missing optional capabilities are reported by `/health` and return a clear +HTTP 422 if you request a feature that needs them. + +> [!NOTE] +> `everos demo --live` is different from the standalone demo in step 2: it +> connects to a running server and uses the real add/flush/search flow. It uses +> hybrid search, so add an embedding provider before you run it. + ### Optional: Ingest Multimodal Files To ingest non-text content (image / pdf / audio / office documents) @@ -271,10 +257,9 @@ extra: 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 -(`EVEROS_MULTIMODAL__*` fields in `.env`, defaults to -`google/gemini-3-flash-preview` via OpenRouter). +This pulls in `everalgo-parser` (with the `[svg]` bundle for SVG support via +cairosvg). Configure the `[multimodal]` section in `everos.toml`; its default +model is `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 @@ -298,7 +283,7 @@ cd EverOS uv sync # creates ./.venv and installs deps 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 init # add one OpenRouter key to ~/.everos/everos.toml everos --help make test diff --git a/README.zh-CN.md b/README.zh-CN.md index 2a15467..d3f1020 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,6 +1,6 @@
-![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2) +![EverOS banner](https://github.com/user-attachments/assets/806e9d7f-c861-4b89-9141-11e38f8753e3)

X @@ -88,25 +88,13 @@ agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB ## 快速开始 -> 目标：先体验 memory visualizer，然后启动 EverOS，写入一条真实记忆， -> 再把它搜索回来。 +> 国内默认使用一个阿里云百炼 DashScope API Key，即可启动 EverOS、写入 +> 持久化记忆，并使用完整的文本检索能力。 -### 0. 前置条件 +### 前置条件 - Python 3.12+ -- `everos demo` 不需要 API keys。 -- 如果要运行真正的 server-backed memory flow，中文默认推荐先在 - [阿里云百炼控制台](https://bailian.console.aliyun.com/) 创建一个 - DashScope API Key： - -| 能力 | 默认 Provider | 用途 | 填入这些 `.env` 字段 | -| --- | --- | --- | --- | -| Chat / extraction | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `LLM` | `EVEROS_LLM__API_KEY` | -| Embedding | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `EMBEDDING` | `EVEROS_EMBEDDING__API_KEY` | -| Re-rank | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `RERANK` | `EVEROS_RERANK__API_KEY` | - -同一个 DashScope API Key 可以填到这三个 slot。多模态文件摄取仍通过 -`EVEROS_MULTIMODAL__*` 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。 +- 一个[阿里云百炼 DashScope API Key](https://bailian.console.aliyun.com/) ### 1. 安装 @@ -115,72 +103,64 @@ uv pip install everos # or: pip install everos ``` -### 2. 体验 Demo +### 2. 先体验独立 Demo —— 不需要 Key -在配置 API keys 或启动 server 之前，先运行： +在配置 provider 或启动 server 之前，先运行： ```bash everos demo ``` -这个命令会询问一条记忆和一个召回问题，然后打开一个全屏 terminal UI。 -这是一个 educational visualizer：它是 hardcoded 的，只在 CLI 本地运行， -不会连接 EverOS server。它的作用是把 memory lifecycle 变成可感知的过程： -conversation -> memory sphere -> recall -> source proof -> confetti。Demo -范围和 TUI 代码结构见 [docs/everos-demo.md](docs/everos-demo.md)。 - -Sphere 会经历 ingest、extraction、indexing、recall、source reveal， -并在第一条记忆落地后进入 confetti successful moment。按 `r` 可以 replay， -按 `q` 可以退出。 +这个命令会询问一条记忆和一个召回问题，然后打开全屏 terminal visualizer。 +它是 hardcoded 的本地 CLI 演示：不需要 API Key，不会启动或连接 EverOS +server，也不会修改下面真实记忆流程的任何数据。

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

-README 媒体使用的循环 showroom view 可以这样运行： +按 `r` replay，按 `q` 退出。非交互式预览可以使用 `everos demo --plain`； +循环 showroom view 可以使用 `everos demo --cinematic`。Visualizer 的范围见 +[docs/everos-demo.md](docs/everos-demo.md)。 -```bash -everos demo --cinematic -``` - -如果 shell 不是 interactive，或者你只想看一个可复制的静态预览： - -```bash -everos demo --plain -``` - -### 3. 配置 - -生成一个 starter `.env` 文件，然后根据生成的注释填入对应的 API key 字段。 -中文 quick start 默认推荐使用 -[阿里云百炼控制台](https://bailian.console.aliyun.com/) 的 DashScope API Key -配置 `LLM` / `EMBEDDING` / `RERANK` 三个核心能力。 +### 3. 初始化并配置百炼 ```bash everos init -# or, from a source checkout: -cp .env.example .env ``` -`everos init` 默认写入 `./.env`。也可以使用 `everos init --xdg` -写入 `${XDG_CONFIG_HOME:-~/.config}/everos/.env`。 +这个命令会创建 `~/.everos/everos.toml` 和 `~/.everos/ome.toml`。打开 +`~/.everos/everos.toml`，配置下面的百炼 provider。 -百炼三件套示例： +在[百炼控制台](https://bailian.console.aliyun.com/)创建一个华北 2（北京）地域的 +DashScope API Key，并把同一个 Key 复用到三个文本 provider： -```env -EVEROS_LLM__MODEL=qwen-plus -EVEROS_LLM__API_KEY= -EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +```toml +[llm] +model = "qwen-plus" +api_key = "" +base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" -EVEROS_EMBEDDING__MODEL=text-embedding-v4 -EVEROS_EMBEDDING__API_KEY= -EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +[embedding] +model = "text-embedding-v4" +api_key = "" +base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1" +dimensions = 1024 -EVEROS_RERANK__MODEL=gte-rerank-v2 -EVEROS_RERANK__API_KEY= -EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com +[rerank] +provider = "dashscope" +model = "gte-rerank-v2" +api_key = "" +base_url = "https://dashscope.aliyuncs.com" ``` +Embedding 会启用 vector 和 user-hybrid retrieval；DashScope rerank 会进一步 +启用 agentic search、默认 agent-hybrid search 和 Knowledge Wiki。共享 DashScope +host 仍支持北京地域的 Key；生产环境可以换成对应地域与业务空间的百炼专属 host。 + +如果希望更换 memory root，可以使用 `everos init --root `。后续命令也要 +传入同一个 `--root `。 + ### 4. 启动 EverOS ```bash @@ -193,30 +173,10 @@ everos server start curl http://127.0.0.1:8000/health ``` -预期响应： +确认响应里有 `"status":"ok"`。上面的百炼配置会显示 `llm`、`embed` 和 +`rerank` 三个文本 capability 均可用。 -```json -{"status":"ok"} -``` - -`everos server start` 会按以下顺序查找 `.env`：`--env-file ` → -`./.env`（当前目录）→ `${XDG_CONFIG_HOME:-~/.config}/everos/.env` → -`~/.everos/.env`。端点栈兼容 OpenAI protocol（OpenAI / OpenRouter / -vLLM / Ollama / DeepInfra）。你可以覆盖生成的 `.env` 中的 `*__BASE_URL` -来指向任意这些模型服务。 - -现在可以把 demo 跑成真实 server flow。在第二个 terminal 里运行： - -```bash -everos demo --live -``` - -Live demo mode 会连接正在运行的 server，并在打开同一个 memory sphere UI -之前真实执行 `/health` -> `/api/v2/memory/add` -> `/api/v2/memory/flush` -> -`/api/v2/memory/search`。如果 server 不在 `http://127.0.0.1:8000`，可以使用 -`--server-url `。 - -### 5. 试写第一条记忆 +### 5. 写入并搜索第一条记忆 > [!NOTE] > 业务接口位于 `/api/v2`。旧的 `/api/v1` 前缀仍然指向同一批 handler，已有集成 @@ -241,7 +201,7 @@ curl -X POST http://127.0.0.1:8000/api/v2/memory/add \ }" ``` -为了本地 demo，手动触发一次 extraction： +在 session 结束时手动 flush 这条记忆： ```bash curl -X POST http://127.0.0.1:8000/api/v2/memory/flush \ @@ -259,12 +219,13 @@ curl -X POST http://127.0.0.1:8000/api/v2/memory/search \ "app_id": "default", "project_id": "default", "query": "Where do I like to climb?", + "method": "hybrid", "top_k": 5 }' ``` -响应里应该能看到 Yosemite 相关记忆。如果第一次搜索为空，稍等片刻再试； -Markdown 会同步写入，本地索引会在后台追上。 +响应里应该能看到 Yosemite 相关记忆。完整百炼配置可以直接使用 hybrid search； +也可以省略 `method` 字段，因为 API 默认就是 hybrid。 > [!TIP] > **第一条记忆已经写入。** @@ -272,7 +233,20 @@ Markdown 会同步写入，本地索引会在后台追上。 > 并通过本地索引把它搜索回来。这就是 EverOS 的核心闭环。 > 想看看 source of truth？打开 `~/.everos`，直接检查生成的 Markdown 文件。 -带完整响应和 Markdown 文件说明的 walkthrough 见 [QUICKSTART.md](QUICKSTART.md)。 +### 一个百炼 Key 可以使用哪些能力？ + +| 配置 | 可用能力 | +| --- | --- | +| 百炼 `[llm]` + `[embedding]` + `[rerank]` | Keyword、vector、hybrid、agentic search；reflection、skill extraction、Knowledge Wiki | +| 再添加 `[multimodal]` 和 parser extra | 图片、PDF、音频、Office 文件摄取 | + +`/health` 会列出缺失的可选能力。如果请求了尚未配置 provider 的功能，API 会 +返回明确的 HTTP 422。 + +> [!NOTE] +> `everos demo --live` 和步骤 2 的独立 Demo 不一样：它会连接正在运行的 server， +> 并执行真实的 add / flush / search 流程。它使用 hybrid search，上面的完整百炼 +> 配置可以直接运行。 ### 可选：摄取多模态文件 @@ -284,8 +258,8 @@ uv pip install 'everos[multimodal]' # or: pip install 'everos[multimodal]' ``` 这会引入 `everalgo-parser`（包含用于 SVG 支持的 `[svg]` bundle，通过 -cairosvg）并接入多模态 LLM client（`.env` 中的 `EVEROS_MULTIMODAL__*` -字段，默认通过 OpenRouter 使用 `google/gemini-3-flash-preview`）。 +cairosvg）。在 `everos.toml` 的 `[multimodal]` 中完成配置；默认模型是通过 +OpenRouter 使用的 `google/gemini-3-flash-preview`。 **Office 文档支持需要 LibreOffice 作为系统依赖。** parser 会调用 `soffice`（LibreOffice 的 headless renderer），先把 `.doc` / `.docx` / @@ -308,7 +282,7 @@ cd EverOS uv sync # creates ./.venv and installs deps source .venv/bin/activate # or prefix commands with `uv run` everos demo --plain # 先体验本地 educational demo；不需要 API keys -everos init # 把百炼 DashScope API Key 填进 .env +everos init # 把一个百炼 DashScope Key 配置到 ~/.everos/everos.toml everos --help make test