docs(readme): refresh banner and localized quickstarts (#401)
* docs(readme): simplify one-key quickstart * docs(readme): replace GitHub banner * docs(readme): restore regional quickstart routes * docs(readme): localize provider quickstarts
This commit is contained in:
Elliot Chen
GitHub
parent
48fc908488
commit
0a7900279c
408
QUICKSTART.md
408
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 <path>` 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 <path>` and pass the same
|
||||
`--root <path>` 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 = "<OPENROUTER_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 <path>] # 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:
|
||||
|
||||
```
|
||||
<root>/ ← ~/.everos or your --root path
|
||||
├── default_app/ ← app_id ("default" → "default_app")
|
||||
│ └── default_project/ ← project_id ("default" → "default_project")
|
||||
│ ├── users/<user_id>/
|
||||
│ │ ├── 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_id>/
|
||||
│ │ ├── 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).
|
||||
|
|
|
|||
143
README.md
143
README.md
|
|
@ -1,6 +1,6 @@
|
|||
<div align="center" id="readme-top">
|
||||
|
||||
|
||||
|
||||
|
||||
<p align="center">
|
||||
<a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a>
|
||||
|
|
@ -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.
|
||||
|
||||
<p align="center">
|
||||
<img src="https://gist.githubusercontent.com/cyfyifanchen/afa2cf40bf138a3ec96d917e8f2791a2/raw/d4ce82a6ddd7b3ebaf221e4825af993aeca5a7ce/everos-demo-tui-animation.svg" alt="Animated EverOS demo preview showing the memory sphere moving through recall and confetti states" width="720">
|
||||
</p>
|
||||
|
||||
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 = "<OPENROUTER_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 <path>` if you want a different memory root. Pass the
|
||||
same `--root <path>` 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 <path>` →
|
||||
`./.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 <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
|
||||
|
|
|
|||
154
README.zh-CN.md
154
README.zh-CN.md
|
|
@ -1,6 +1,6 @@
|
|||
<div align="center" id="readme-top">
|
||||
|
||||
|
||||
|
||||
|
||||
<p align="center">
|
||||
<a href="https://x.com/evermind"><img src="https://img.shields.io/badge/EverMind-000000?labelColor=gray&style=for-the-badge&logo=x&logoColor=white" alt="X"></a>
|
||||
|
|
@ -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，也不会修改下面真实记忆流程的任何数据。
|
||||
|
||||
<p align="center">
|
||||
<img src="https://gist.githubusercontent.com/cyfyifanchen/afa2cf40bf138a3ec96d917e8f2791a2/raw/d4ce82a6ddd7b3ebaf221e4825af993aeca5a7ce/everos-demo-tui-animation.svg" alt="Animated EverOS demo preview showing the memory sphere moving through recall and confetti states" width="720">
|
||||
</p>
|
||||
|
||||
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=<DASHSCOPE_API_KEY>
|
||||
EVEROS_LLM__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
```toml
|
||||
[llm]
|
||||
model = "qwen-plus"
|
||||
api_key = "<DASHSCOPE_API_KEY>"
|
||||
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
|
||||
EVEROS_EMBEDDING__MODEL=text-embedding-v4
|
||||
EVEROS_EMBEDDING__API_KEY=<DASHSCOPE_API_KEY>
|
||||
EVEROS_EMBEDDING__BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
|
||||
[embedding]
|
||||
model = "text-embedding-v4"
|
||||
api_key = "<DASHSCOPE_API_KEY>"
|
||||
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
dimensions = 1024
|
||||
|
||||
EVEROS_RERANK__MODEL=gte-rerank-v2
|
||||
EVEROS_RERANK__API_KEY=<DASHSCOPE_API_KEY>
|
||||
EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com
|
||||
[rerank]
|
||||
provider = "dashscope"
|
||||
model = "gte-rerank-v2"
|
||||
api_key = "<DASHSCOPE_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 <path>`。后续命令也要
|
||||
传入同一个 `--root <path>`。
|
||||
|
||||
### 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 <path>` →
|
||||
`./.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 <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
|
||||
|
|
|
|||
Loading…
Reference in New Issue