From feb811e51c72c61d08635304399b1149d042744b Mon Sep 17 00:00:00 2001
From: Elliot Chen <cyfyifanchen@gmail.com>
Date: Sat, 27 Jun 2026 10:08:44 +0800
Subject: [PATCH 1/6] docs: align config and positioning copy

---
 CITATION.md                    |  6 +--
 QUICKSTART.md                  | 40 ++++++++-------
 README.md                      | 69 +++++++++++++++-----------
 README.zh-CN.md                | 91 +++++++++++++++++++---------------
 SECURITY.md                    |  9 ++--
 docs/configuration.md          | 10 ++--
 docs/index.md                  |  1 +
 docs/positioning.md            | 73 +++++++++++++++++++++++++++
 docs/use-cases.md              |  2 +-
 src/everos/config/default.toml | 16 +++---
 use-cases/README.md            |  2 +-
 11 files changed, 212 insertions(+), 107 deletions(-)
 create mode 100644 docs/positioning.md

diff --git a/CITATION.md b/CITATION.md
index 3db0c9093..2b16b357b 100644
--- a/CITATION.md
+++ b/CITATION.md
@@ -32,9 +32,9 @@ BibTeX citation information will be added here once the paper is published.
 To cite the software itself:
 
 ```
-EverOS: md-first memory extraction framework for AI agents
-Version: 0.1.0
-URL: https://github.com/EverMind-AI/everos
+EverOS: local-first memory runtime for AI agents
+Version: 1.1.0
+URL: https://github.com/EverMind-AI/EverOS
 License: Apache 2.0
 ```
 
diff --git a/QUICKSTART.md b/QUICKSTART.md
index dfd19f140..250dfde43 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -10,15 +10,19 @@ front of your agent.
 ## Prerequisites
 
 - **Python 3.12+**
-- **An OpenRouter API key** — covers the chat LLM (memory extraction)
-  *and* the multimodal LLM (parsing image / pdf / audio content items)
-  with a single key.
-- **A DeepInfra API key** — for the embedding + rerank models that
-  OpenRouter doesn't ship.
-
-Two keys total. Any OpenAI-compatible endpoint plugs in via the
-matching `*__BASE_URL` env var if you'd rather use OpenAI directly,
-self-host vLLM, route to Ollama, etc.
+- **An LLM provider key and endpoint** — for memory extraction. OpenRouter,
+  OpenAI, and other OpenAI-compatible providers work when you set
+  `base_url`.
+- **A multimodal provider key and endpoint** — needed only when parsing
+  image / pdf / audio content items.
+- **Embedding and rerank provider keys and endpoints** — for search. DeepInfra
+  works for the embedding + rerank path; vLLM and DashScope are also supported
+  for rerank.
+
+Many deployments use two distinct keys by reusing one LLM key for `[llm]` and
+`[multimodal]`, and one DeepInfra key for `[embedding]` and `[rerank]`. Any
+setting can live in TOML or be overridden by the matching `EVEROS_*`
+environment variable.
 
 ## 1. Install
 
@@ -29,15 +33,15 @@ pip install everos
 
 ## 2. Configure
 
-Generate the starter config and drop in your two keys:
+Generate the starter config and fill in provider credentials:
 
 ```bash
 everos init                    # writes ~/.everos/everos.toml + ome.toml (use --root to relocate)
-# Edit ~/.everos/everos.toml and fill four api_key slots (only two distinct keys needed):
-#   [llm]        api_key   (OpenRouter — chat LLM)
-#   [multimodal] api_key   (OpenRouter — same key works)
-#   [embedding]  api_key   (DeepInfra)
-#   [rerank]     api_key   (DeepInfra — same key works)
+# Edit ~/.everos/everos.toml and fill the provider fields:
+#   [llm]        api_key + base_url             (chat LLM)
+#   [multimodal] api_key + base_url             (optional parser LLM)
+#   [embedding]  model + api_key + base_url
+#   [rerank]     model + api_key + base_url     (provider can be inferred or set)
 ```
 
 `everos init` generates two files: `everos.toml` (provider settings)
@@ -48,9 +52,9 @@ after editing: `chmod 600 ~/.everos/everos.toml`.
 The shipped template sets model defaults for `[llm]` (`gpt-4.1-mini`) and
 `[multimodal]` (`google/gemini-3-flash-preview`); `[embedding]` and
 `[rerank]` ship no model default — set `model` + `base_url` for those two
-sections yourself (e.g. DeepInfra's `Qwen/Qwen3-Embedding-4B` /
-`Qwen/Qwen3-Reranker-4B`). To use a different OpenAI-compatible endpoint
-for any provider, set the matching `base_url` field.
+sections yourself (for example DeepInfra's `Qwen/Qwen3-Embedding-4B` /
+`Qwen/Qwen3-Reranker-4B`). `[llm]` and `[multimodal]` ship model defaults,
+but still need `api_key` and `base_url` before those capabilities are used.
 
 > **Where config lives** — `everos init` writes into the memory root
 > (`~/.everos` by default; relocate with `everos init --root <path>` and
diff --git a/README.md b/README.md
index 7f221d8b7..3e5ea97bc 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,10 @@
 <div align="center" id="readme-top">
 
-![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)
+<h1 align="center">EverOS</h1>
+
+<p align="center"><strong>Local-first memory for AI agents, stored as Markdown.</strong></p>
+
+<p align="center">Markdown source of truth · SQLite + LanceDB · User + agent memory · Knowledge + Reflection</p>
 
 <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>
@@ -21,7 +25,7 @@
 
 <br>
 
-- [Why Ever OS](#why-ever-os)
+- [Why EverOS](#why-everos)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
 - [Documentation](#documentation)
@@ -34,13 +38,13 @@
 </details>
 
 
-## Why Ever OS
+## Why EverOS
 
-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.
+EverOS is a 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 retrieval,
+search, and background memory evolution.
 
 <table>
 <tr>
@@ -99,13 +103,13 @@ for fast retrieval and self-evolving reuse.
 - To run the real server-backed memory flow, create two provider keys before
   `everos init`:
 
-| Capability | Provider | Used for | Fill these `.env` slots |
+| Capability | Provider path | Used for | Configure in `everos.toml` |
 | --- | --- | --- | --- |
-| 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` |
+| Chat + multimodal | Any OpenAI-compatible LLM endpoint, such as [OpenRouter](https://openrouter.ai/) or OpenAI | `LLM` / `MULTIMODAL` | `[llm]` and `[multimodal]` `api_key`, `base_url`, and model fields |
+| Embedding + rerank | OpenAI-compatible embeddings plus DeepInfra / vLLM / DashScope rerank | `EMBEDDING` / `RERANK` | `[embedding]` and `[rerank]` `api_key`, `base_url`, and model fields |
 
-You can use other OpenAI-compatible providers by changing the matching
-`*__BASE_URL` fields in `.env`.
+You can also override any TOML field with the matching environment variable,
+for example `EVEROS_LLM__BASE_URL` or `EVEROS_EMBEDDING__API_KEY`.
 
 ### 1. Install
 
@@ -151,19 +155,17 @@ 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.
+Generate starter TOML files, then fill in provider credentials and endpoints in
+`~/.everos/everos.toml`. The second file, `ome.toml`, controls the offline
+memory engine schedule.
 
 ```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.
+`everos init` writes `~/.everos/everos.toml` and `~/.everos/ome.toml` by
+default. Use `everos init --root /path/to/everos` to choose another memory
+root.
 
 ### 4. Start EverOS
 
@@ -183,11 +185,10 @@ Expected response:
 {"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.
+`everos server start` reads `<root>/everos.toml` and exits if the file is
+missing. The endpoint stack is OpenAI-protocol compatible; set each provider's
+`base_url` in TOML, or override it with `EVEROS_*__BASE_URL` environment
+variables for containers and CI.
 
 Now make the demo real. In the second terminal, run:
 
@@ -268,8 +269,8 @@ 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).
+(`[multimodal]` in `everos.toml`, or `EVEROS_MULTIMODAL__*` environment
+overrides).
 
 **Office document support requires LibreOffice as a system dependency.**
 The parser shells out to `soffice` (LibreOffice's headless renderer) to
@@ -293,7 +294,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                          # create ~/.everos/everos.toml + ome.toml
 
 everos --help
 make test
@@ -465,7 +466,7 @@ Ruminer brings persistent memory to a browser agent so it can carry personal con
 
 #### EverMem Sync With EverOS
 
-One command to connect any AI coding CLI to EverMemOS long-term memory.
+One command to connect any AI coding CLI to EverOS long-term memory.
 
 [Code](https://github.com/nanxingw/EverMem)
 
@@ -641,6 +642,14 @@ Explore stored entities and relationships in a graph interface. Frontend demo; b
 
 ## Documentation
 
+- [docs/index.md](docs/index.md) — Documentation map
+- [QUICKSTART.md](QUICKSTART.md) — Five-minute service + memory walkthrough
+- [docs/overview.md](docs/overview.md) — Project vision, scope, and design philosophy
+- [docs/positioning.md](docs/positioning.md) — Public GTM language, banner direction, and competitor framing
+- [docs/configuration.md](docs/configuration.md) — TOML and environment-variable configuration reference
+- [docs/api.md](docs/api.md) — HTTP API v1 reference
+- [docs/knowledge.md](docs/knowledge.md) — Knowledge base module
+- [docs/reflection.md](docs/reflection.md) — Offline memory consolidation
 - [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
diff --git a/README.zh-CN.md b/README.zh-CN.md
index b7a899e9c..01dcc9097 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,6 +1,10 @@
 <div align="center" id="readme-top">
 
-![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)
+<h1 align="center">EverOS</h1>
+
+<p align="center"><strong>面向 AI agents 的 local-first Markdown 记忆运行时。</strong></p>
+
+<p align="center">Markdown source of truth · SQLite + LanceDB · 用户 + Agent 双轨记忆 · Knowledge + Reflection</p>
 
 <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>
@@ -36,11 +40,11 @@
 
 ## 为什么选择 EverOS
 
-EverOS 是面向 agents 和 makers 的 Python library 与 local-first memory
-runtime。它从 day one 开始就提供一层可携带的记忆层，让记忆穿过 coding
-assistants、apps、devices 和 workflows。它会把 conversations、files 和
-agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB
-索引，用于快速检索和自进化复用。
+EverOS 是面向 agents 和 makers 的 local-first memory runtime。它从 day
+one 开始就提供一层可携带的记忆层，让记忆穿过 coding assistants、apps、
+devices 和 workflows。它会把 conversations、files 和 agent trajectories
+保存为可读 Markdown，并同步本地 SQLite 与 LanceDB 索引，用于检索、搜索
+和后台记忆进化。
 
 <table>
 <tr>
@@ -100,14 +104,14 @@ agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB
   [阿里云百炼控制台](https://bailian.console.aliyun.com/) 创建一个
   DashScope API Key：
 
-| 能力 | 默认 Provider | 用途 | 填入这些 `.env` 字段 |
+| 能力 | 默认 Provider | 用途 | 配置到 `everos.toml` |
 | --- | --- | --- | --- |
-| 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` |
+| Chat / extraction | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `LLM` | `[llm]` 的 `model`、`api_key`、`base_url` |
+| Embedding | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `EMBEDDING` | `[embedding]` 的 `model`、`api_key`、`base_url` |
+| Re-rank | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `RERANK` | `[rerank]` 的 `provider`、`model`、`api_key`、`base_url` |
 
-同一个 DashScope API Key 可以填到这三个 slot。多模态文件摄取仍通过
-`EVEROS_MULTIMODAL__*` 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。
+同一个 DashScope API Key 可以填到这三个 section。多模态文件摄取仍通过
+`[multimodal]` 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。
 
 ### 1. 安装
 
@@ -152,34 +156,36 @@ everos demo --plain
 
 ### 3. 配置
 
-生成一个 starter `.env` 文件，然后根据生成的注释填入对应的 API key 字段。
-中文 quick start 默认推荐使用
+生成 starter TOML 文件，然后在 `~/.everos/everos.toml` 中填入模型、
+endpoint 和 API key。中文 quick start 默认推荐使用
 [阿里云百炼控制台](https://bailian.console.aliyun.com/) 的 DashScope API Key
 配置 `LLM` / `EMBEDDING` / `RERANK` 三个核心能力。
 
 ```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 init` 默认写入 `~/.everos/everos.toml` 和 `~/.everos/ome.toml`。
+也可以使用 `everos init --root /path/to/everos` 指定 memory root。
 
 百炼三件套示例：
 
-```env
-EVEROS_LLM__MODEL=qwen-plus
-EVEROS_LLM__API_KEY=<DASHSCOPE_API_KEY>
-EVEROS_LLM__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
-
-EVEROS_RERANK__MODEL=gte-rerank-v2
-EVEROS_RERANK__API_KEY=<DASHSCOPE_API_KEY>
-EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com
+```toml
+[llm]
+model = "qwen-plus"
+api_key = "<DASHSCOPE_API_KEY>"
+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"
+
+[rerank]
+provider = "dashscope"
+model = "gte-rerank-v2"
+api_key = "<DASHSCOPE_API_KEY>"
+base_url = "https://dashscope.aliyuncs.com"
 ```
 
 ### 4. 启动 EverOS
@@ -200,11 +206,10 @@ curl http://127.0.0.1:8000/health
 {"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`
-来指向任意这些模型服务。
+`everos server start` 会读取 `<root>/everos.toml`；如果文件不存在，会提示先
+运行 `everos init`。端点栈兼容 OpenAI protocol。你可以在 TOML 中设置各
+provider 的 `base_url`，也可以用 `EVEROS_*__BASE_URL` 环境变量覆盖，方便
+container 和 CI 使用。
 
 现在可以把 demo 跑成真实 server flow。在第二个 terminal 里运行：
 
@@ -280,8 +285,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）并接入多模态 LLM client（`everos.toml` 中的 `[multimodal]`
+section，或 `EVEROS_MULTIMODAL__*` 环境变量覆盖）。
 
 **Office 文档支持需要 LibreOffice 作为系统依赖。** parser 会调用
 `soffice`（LibreOffice 的 headless renderer），先把 `.doc` / `.docx` /
@@ -304,7 +309,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                          # 创建 ~/.everos/everos.toml + ome.toml
 
 everos --help
 make test
@@ -474,7 +479,7 @@ Ruminer 为 browser agent 带来持久记忆，让它能在不同网页任务之
 
 #### EverMem 与 EverOS 同步
 
-一条命令，把任意 AI coding CLI 连接到 EverMemOS 长期记忆。
+一条命令，把任意 AI coding CLI 连接到 EverOS 长期记忆。
 
 [代码](https://github.com/nanxingw/EverMem)
 
@@ -650,6 +655,14 @@ Claude Code 的持久记忆插件。自动保存并回忆过去 coding sessions
 
 ## 文档
 
+- [docs/index.md](docs/index.md) - 文档地图
+- [QUICKSTART.md](QUICKSTART.md) - 5 分钟 service + memory walkthrough
+- [docs/overview.md](docs/overview.md) - 项目愿景、范围与设计哲学
+- [docs/positioning.md](docs/positioning.md) - GTM 文案、banner 方向与竞品 framing
+- [docs/configuration.md](docs/configuration.md) - TOML 与环境变量配置参考
+- [docs/api.md](docs/api.md) - HTTP API v1 参考
+- [docs/knowledge.md](docs/knowledge.md) - Knowledge base 模块
+- [docs/reflection.md](docs/reflection.md) - 离线记忆 consolidation
 - [docs/everos-demo.md](docs/everos-demo.md) - Demo 范围与 TUI 源码布局
 - [docs/how-memory-works.md](docs/how-memory-works.md) - Markdown、SQLite、LanceDB 与 recall flow
 - [docs/use-cases.md](docs/use-cases.md) - 完整使用场景 gallery 和集成示例
diff --git a/SECURITY.md b/SECURITY.md
index 60f6e22e3..487c8fd8a 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,7 +2,7 @@
 
 ## Supported Versions
 
-EverOS is released and at v1.0.0 (stable). Security fixes are applied to the
+EverOS is released and in the v1.x stable line. Security fixes are applied to the
 latest release line only.
 
 | Version | Supported |
@@ -39,8 +39,9 @@ following in mind:
   is loopback-only. Only set the bind to `0.0.0.0` (or any routable interface)
   after you have placed your own gateway / auth layer in front;
   `everos server start` will log a warning when you bind to `0.0.0.0`.
-- Secrets (LLM / embedding API keys) live in your local `.env`; protect that
-  file as you would any credential. EverOS never transmits them anywhere except
-  the providers you configure.
+- Secrets (LLM / embedding / rerank API keys) normally live in your local
+  `<root>/everos.toml`, or in `EVEROS_*` environment variables for container
+  deployments. Protect those values as you would any credential. EverOS never
+  transmits them anywhere except the providers you configure.
 - Memory content is stored as plaintext `.md` files; apply OS-level file
   permissions or disk encryption if your data is sensitive.
diff --git a/docs/configuration.md b/docs/configuration.md
index eda0f4964..22e2c4cde 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -105,7 +105,7 @@ everos init --root /data/everos
 |---|---|---|---|---|
 | `model` | string | `"gpt-4.1-mini"` | No | LLM model identifier. |
 | `api_key` | string | — | **Yes** | API key for the LLM provider. |
-| `base_url` | string | — | No | Custom endpoint URL (OpenAI-compatible). |
+| `base_url` | string | — | **Yes** | Endpoint URL (OpenAI-compatible). |
 
 ### `[multimodal]`
 
@@ -113,7 +113,7 @@ everos init --root /data/everos
 |---|---|---|---|---|
 | `model` | string | `"google/gemini-3-flash-preview"` | No | Multimodal parsing model. |
 | `api_key` | string | — | **Yes** | API key. |
-| `base_url` | string | — | No | Custom endpoint URL. |
+| `base_url` | string | — | **Yes** | Endpoint URL. |
 | `max_concurrency` | int | `4` | No | Max parallel parsing requests. |
 | `file_uri_allow_dirs` | list[string] | `[]` | No | Allowlisted base dirs for `file://` URIs. Empty = allow any readable file. |
 | `file_uri_max_bytes` | int | `52428800` | No | Max size (bytes) of a `file://` asset; larger files are rejected. |
@@ -134,7 +134,7 @@ everos init --root /data/everos
 
 | Field | Type | Default | Required | Description |
 |---|---|---|---|---|
-| `provider` | string | `"deepinfra"` | No | Rerank provider: `deepinfra` or `vllm`. |
+| `provider` | string | inferred | No | Rerank provider: `deepinfra`, `vllm`, or `dashscope`. |
 | `model` | string | — | **Yes** | Reranker model identifier. |
 | `api_key` | string | — | **Yes** | API key. |
 | `base_url` | string | — | **Yes** | Rerank endpoint URL. |
@@ -210,9 +210,13 @@ variables directly:
 ENV EVEROS_ROOT=/data/everos
 ENV EVEROS_LLM__API_KEY=sk-...
 ENV EVEROS_LLM__MODEL=gpt-4o
+ENV EVEROS_LLM__BASE_URL=https://api.openai.com/v1
 ENV EVEROS_EMBEDDING__MODEL=text-embedding-3-large
 ENV EVEROS_EMBEDDING__API_KEY=sk-...
 ENV EVEROS_EMBEDDING__BASE_URL=https://api.openai.com/v1
+ENV EVEROS_RERANK__MODEL=Qwen/Qwen3-Reranker-4B
+ENV EVEROS_RERANK__API_KEY=...
+ENV EVEROS_RERANK__BASE_URL=https://api.deepinfra.com/v1/inference
 ENV EVEROS_API__HOST=0.0.0.0
 ENV EVEROS_API__PORT=8000
 ```
diff --git a/docs/index.md b/docs/index.md
index 3b5935275..fecd29d72 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -38,6 +38,7 @@ why the system is shaped the way it is.
 | Doc | Purpose |
 |---|---|
 | [overview.md](overview.md) | Project vision, scope, design philosophy |
+| [positioning.md](positioning.md) | Public GTM language, proof points, banner direction, and competitor framing |
 | [how-memory-works.md](how-memory-works.md) | Storage stack + on-disk paths + write→index→read pipeline + consistency |
 | [architecture.md](architecture.md) | DDD layered architecture + dependency rules |
 | [datetime.md](datetime.md) | Two-zone discipline — UTC at storage, display tz at boundaries |
diff --git a/docs/positioning.md b/docs/positioning.md
new file mode 100644
index 000000000..705d4f862
--- /dev/null
+++ b/docs/positioning.md
@@ -0,0 +1,73 @@
+# Positioning
+
+This page keeps EverOS public language consistent across the README, docs,
+release notes, banners, and demos.
+
+## Category
+
+EverOS is a **local-first memory runtime for AI agents**.
+
+Use this category when the audience cares about agent infrastructure,
+developer tools, and local data ownership. Avoid positioning EverOS as only a
+vector database, RAG library, chat-history SDK, or dashboard.
+
+## One-Liner
+
+EverOS gives agents long-term memory stored as readable Markdown, with local
+SQLite and LanceDB indexes rebuilt from that source of truth.
+
+## Primary Proof Points
+
+- Markdown source of truth: readable, editable, diffable, and Git-versioned.
+- Local runtime stack: Markdown + SQLite + LanceDB, no required hosted database.
+- User + agent memory tracks: user episodes/profile and agent cases/skills are
+  separate first-class surfaces.
+- Knowledge + Reflection: source-backed knowledge pages and offline memory
+  consolidation extend beyond retrieval-only memory.
+- Rebuildable indexes: derived SQLite and LanceDB state can be regenerated from
+  the Markdown files.
+
+## Claims To Avoid Without Fresh Evidence
+
+Do not use benchmark or research claims in public hero copy unless they link to
+an owned benchmark or citation page in this repository.
+
+Avoid unsupported claims such as:
+
+- Exact LoCoMo accuracy numbers.
+- Exact p95 latency numbers.
+- Exact token-savings percentages.
+- Paper counts or publication claims.
+- "Best", "fastest", or "most accurate" market-wide comparisons.
+
+Use capability language instead:
+
+- "Local-first memory for AI agents, stored as Markdown."
+- "Memory agents can read, edit, search, and evolve."
+- "A Markdown-native memory runtime for AI agents."
+
+## Comparison Notes
+
+These notes are for maintainers writing public copy. Keep comparisons factual,
+linked, and framed around fit rather than winner-takes-all claims.
+
+| Project | Public positioning | EverOS distinction |
+|---|---|---|
+| [Mem0](https://github.com/mem0ai/mem0) | Universal memory layer with SDKs, CLI, integrations, self-hosted server, and managed platform paths. | Position EverOS around local-first ownership, Markdown source files, direct file editing, and rebuildable local indexes. |
+| [MemOS](https://github.com/MemTensor/MemOS) | Memory OS / memory-augmented generation system for persistent memory, hybrid retrieval, and cross-task skill reuse. | Position EverOS as the practical local runtime with a concrete Markdown + SQLite + LanceDB storage model rather than a broad memory-OS taxonomy. |
+| [OpenViking](https://github.com/volcengine/OpenViking) | Context database for AI agents using a filesystem paradigm for context, memory, resources, and skills. | Position EverOS around memory extraction, Markdown source of truth, Knowledge, Reflection, and derived indexes, not just context storage. |
+| [MemPalace](https://github.com/MemPalace/mempalace) | Personal memory OS for agents and developers, with local-first and integration-oriented workflows. | Position EverOS around typed storage boundaries, source-backed Markdown, tested cascade/index rebuilds, and first-class user + agent memory tracks. |
+
+## Banner Direction
+
+Prefer a capability-led banner over metric-led copy:
+
+```text
+EverOS
+Local-first memory for AI agents, stored as Markdown.
+Markdown source of truth · SQLite + LanceDB · User + agent memory · Knowledge + Reflection
+```
+
+When metrics are available, link the banner or README badge to the benchmark
+page that explains model stack, dataset, hardware, sample size, and command to
+reproduce the result.
diff --git a/docs/use-cases.md b/docs/use-cases.md
index 05d015d33..aa31dcbd7 100644
--- a/docs/use-cases.md
+++ b/docs/use-cases.md
@@ -147,7 +147,7 @@ Ruminer brings persistent memory to a browser agent so it can carry personal con
 
 #### EverMem Sync with EverOS
 
-One command to connect any AI coding CLI to EverMemOS long-term memory.
+One command to connect any AI coding CLI to EverOS long-term memory.
 
 [Code](https://github.com/nanxingw/EverMem)
 
diff --git a/src/everos/config/default.toml b/src/everos/config/default.toml
index d96a439d6..ad9bf7b58 100644
--- a/src/everos/config/default.toml
+++ b/src/everos/config/default.toml
@@ -131,6 +131,14 @@ vector_strategy = "maxsim_atomic"
 # requires a restart. Override via EVEROS_MEMORIZE__MODE.
 mode = "agent"
 
+# Maximum wall-clock for one memorize() invocation while holding the
+# per-session lock. On timeout the outer asyncio.timeout cancels the call
+# and the lock auto-releases so subsequent concurrent /add on the same
+# session aren't deadlocked. Covers boundary LLM + memcell writes +
+# synchronous portion of pipeline dispatch.
+# Override via EVEROS_MEMORIZE__SESSION_LOCK_TIMEOUT_SECONDS.
+session_lock_timeout_seconds = 360.0
+
 [knowledge]
 # Max bytes for an uploaded knowledge document (default 50 MiB). Oversized
 # uploads are rejected with HTTP 422 before parsing/extraction. Note: the
@@ -147,14 +155,6 @@ lambda = 0.1
 mass_top_m = 50
 top_k_cap = 100
 
-# Maximum wall-clock for one memorize() invocation while holding the
-# per-session lock. On timeout the outer asyncio.timeout cancels the call
-# and the lock auto-releases so subsequent concurrent /add on the same
-# session aren't deadlocked. Covers boundary LLM + memcell writes +
-# synchronous portion of pipeline dispatch.
-# Override via EVEROS_MEMORIZE__SESSION_LOCK_TIMEOUT_SECONDS.
-session_lock_timeout_seconds = 360.0
-
 [clustering]
 # Geometry-clustering: cosine similarity threshold and time window.
 # Episodes older than ``time_window_days`` from the newest cluster
diff --git a/use-cases/README.md b/use-cases/README.md
index 88c52e82f..8bfb03dca 100644
--- a/use-cases/README.md
+++ b/use-cases/README.md
@@ -145,7 +145,7 @@ Ruminer brings persistent memory to a browser agent so it can carry personal con
 
 #### EverMem Sync with EverOS
 
-One command to connect any AI coding CLI to EverMemOS long-term memory.
+One command to connect any AI coding CLI to EverOS long-term memory.
 
 [Code](https://github.com/nanxingw/EverMem)
 

From 281a10d2dcc96ec9d8f63de2868644e153c7b809 Mon Sep 17 00:00:00 2001
From: Elliot Chen <cyfyifanchen@gmail.com>
Date: Sat, 27 Jun 2026 10:16:18 +0800
Subject: [PATCH 2/6] docs: remove internal branch workflow residue

---
 .claude/skills/commit/SKILL.md                |   4 +-
 .claude/skills/new-branch/SKILL.md            |  39 ++---
 .claude/skills/pr/SKILL.md                    |  10 +-
 .github/workflows/docs.yml                    |   8 ++
 CLAUDE.md                                     |   7 +-
 CONTRIBUTING.md                               |   4 +-
 Makefile                                      |  10 +-
 scripts/check_github_contributor_docs.py      | 133 ++++++++++++++++++
 .../test_check_github_contributor_docs.py     |  74 ++++++++++
 9 files changed, 259 insertions(+), 30 deletions(-)
 create mode 100644 scripts/check_github_contributor_docs.py
 create mode 100644 tests/unit/test_scripts/test_check_github_contributor_docs.py

diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md
index 98f1f4af7..7faea2ce5 100644
--- a/.claude/skills/commit/SKILL.md
+++ b/.claude/skills/commit/SKILL.md
@@ -26,8 +26,8 @@ standard. The format is enforced by `gitlint` in the `commit-msg` hook.
    ```
 
 5. Never use `--no-verify`. If pre-commit hooks fail, fix the cause and re-commit.
-6. Do not commit secrets, generated artifacts, or work-in-progress to a
-   protected branch (`main` / `dev` / `master`).
+6. Do not commit secrets, generated artifacts, or work-in-progress directly to
+   the protected `main` branch.
 
 ## Types
 
diff --git a/.claude/skills/new-branch/SKILL.md b/.claude/skills/new-branch/SKILL.md
index 9750737a5..7ea2c9831 100644
--- a/.claude/skills/new-branch/SKILL.md
+++ b/.claude/skills/new-branch/SKILL.md
@@ -1,43 +1,44 @@
 ---
 name: new-branch
-description: Create a branch following the project's GitFlow Lite model
+description: Create a GitHub branch from main with the project naming convention
 ---
 
 # /new-branch
 
-Cut a new branch under the GitFlow Lite model.
+Cut a new branch for the GitHub repository.
 
 ## Branch model
 
 ```
-master  = released / stable (tagged on release; protected)
-dev     = integration branch (protected)
-feat/*  = cut from dev  → PR → merge into dev
-fix/*   = cut from dev  → PR → merge into dev
-hotfix/* = cut from master → merge into master AND synced into dev (double merge)
-release  = dev → master + tag on master (no separate release branch)
+main       = default and protected branch
+feat/*     = feature work
+fix/*      = bug fixes
+docs/*     = documentation-only changes
+ci/*       = CI, build, and developer-experience changes
+chore/*    = repository maintenance
+refactor/* = behavior-preserving code structure changes
 ```
 
 ## Steps
 
-1. Ask (or infer) the change type: `feat`, `fix`, or `hotfix`.
-2. Pick the parent:
-   - `feat/*`, `fix/*` → branch from **`dev`**.
-   - `hotfix/*` → branch from **`master`**.
-3. Update the parent first:
+1. Ask (or infer) the change type: `feat`, `fix`, `docs`, `ci`, `chore`, or
+   `refactor`.
+2. Update `main` first:
    ```bash
-   git checkout <parent>
+   git checkout main
    git pull --ff-only
    ```
-4. Create the branch with a kebab-case slug:
+3. Create the branch with a kebab-case slug:
    ```bash
-   git checkout -b feat/<short-slug>
+   git checkout -b <type>/<short-slug>
    ```
-5. For a `hotfix`, remember it must later merge into **both** `master` and `dev`.
+4. Keep the branch scoped to one purpose and open a pull request back to
+   `main`.
 
 ## Naming
 
-- `feat/add-agentic-rerank`, `fix/empty-profile-crash`, `hotfix/lancedb-conn-leak`.
+- `feat/add-agentic-rerank`, `fix/empty-profile-crash`,
+  `docs/quickstart-config`, `ci/check-github-docs`.
 - Lowercase, hyphen-separated, no spaces, concise.
 
-Never commit directly to `master` or `dev` — always via a branch + PR.
+Never commit directly to `main` — always use a branch and pull request.
diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md
index 8a2a7aa32..d24a3217d 100644
--- a/.claude/skills/pr/SKILL.md
+++ b/.claude/skills/pr/SKILL.md
@@ -10,8 +10,9 @@ Open a pull request on GitHub using the `gh` CLI and the repo's PR template.
 ## Steps
 
 1. Confirm the branch and target:
-   - `feat/*`, `fix/*` → base **`dev`**.
-   - `hotfix/*` → base **`master`** (then a follow-up PR/sync into `dev`).
+   - Base branch is **`main`**.
+   - Head branch should be a scoped branch such as `feat/*`, `fix/*`,
+     `docs/*`, `ci/*`, `chore/*`, or `refactor/*`.
 2. Ensure local checks pass first:
    ```bash
    make ci
@@ -24,7 +25,7 @@ Open a pull request on GitHub using the `gh` CLI and the repo's PR template.
 4. Create the PR, filling the template
    ([.github/PULL_REQUEST_TEMPLATE.md](../../../.github/PULL_REQUEST_TEMPLATE.md)):
    ```bash
-   gh pr create --base dev --fill-first
+   gh pr create --base main --fill-first
    ```
    Then edit the body to complete each section:
    - **Summary** — what changed and why.
@@ -38,4 +39,5 @@ Open a pull request on GitHub using the `gh` CLI and the repo's PR template.
 
 - Keep the PR scoped to one area. Split unrelated changes.
 - If `make ci` was not fully run, say so in Verification rather than implying it passed.
-- A `hotfix` is not done until it has landed on **both** `master` and `dev`.
+- Never retarget a community PR away from `main` unless a maintainer explicitly
+  asks for it.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 6f6fa310c..0d2324598 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -7,7 +7,11 @@ on:
       - ".github/ISSUE_TEMPLATE/**"
       - ".github/PULL_REQUEST_TEMPLATE.md"
       - ".github/workflows/docs.yml"
+      - ".claude/skills/**/*.md"
+      - "CLAUDE.md"
+      - "CONTRIBUTING.md"
       - "scripts/check_docs.py"
+      - "scripts/check_github_contributor_docs.py"
   push:
     branches: [main]
     paths:
@@ -15,7 +19,11 @@ on:
       - ".github/ISSUE_TEMPLATE/**"
       - ".github/PULL_REQUEST_TEMPLATE.md"
       - ".github/workflows/docs.yml"
+      - ".claude/skills/**/*.md"
+      - "CLAUDE.md"
+      - "CONTRIBUTING.md"
       - "scripts/check_docs.py"
+      - "scripts/check_github_contributor_docs.py"
 
 permissions:
   contents: read
diff --git a/CLAUDE.md b/CLAUDE.md
index 18110ebf0..b0a33eca4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,9 +47,12 @@ Contributor engineering reference — build, test, CI gates, branch & commit con
 
 ## Branch strategy
 
-`master` = released stable (hidden); `dev` = integration; `feat/* fix/*` → dev; `hotfix/*` → master + dev (sync).
+`main` is the default and protected branch. Create scoped branches from
+`main` (`feat/*`, `fix/*`, `docs/*`, `ci/*`, `chore/*`, `refactor/*`) and open
+pull requests back to `main` after the required checks pass.
 
-See [.claude/skills/new-branch/SKILL.md](.claude/skills/new-branch/SKILL.md) for the full GitFlow Lite rationale.
+See [.claude/skills/new-branch/SKILL.md](.claude/skills/new-branch/SKILL.md)
+for the full branch workflow.
 
 ## Storage three-piece set
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index defeb22cf..6cfd24f8b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -91,7 +91,7 @@ internally.
 git clone https://github.com/EverMind-AI/EverOS.git
 cd EverOS
 make install             # deps + pre-commit hooks (one-stop dev setup)
-everos init              # write ./.env, then fill in the API key slots
+everos init              # write ~/.everos/everos.toml + ome.toml
 make ci                  # verify: lint + unit + integration + package
 ```
 
@@ -153,7 +153,7 @@ Full conventions: [.claude/rules/testing.md](.claude/rules/testing.md).
 
 - `/new-branch` — create branch with proper naming
 - `/commit` — generate a Conventional Commits message
-- `/pr` — internal merge request with correct target branch
+- `/pr` — open a GitHub pull request with the correct target branch
 
 ---
 
diff --git a/Makefile b/Makefile
index d6f633a99..338f749ea 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help install install-deps lint docs-check check-commits check-pr-title check-assets check-deprecated-names check-cjk check-datetime openapi check-openapi format test integration package cov ci clean
+.PHONY: help install install-deps lint docs-check check-commits check-pr-title check-assets check-deprecated-names check-github-docs check-cjk check-datetime openapi check-openapi format test integration package cov ci clean
 
 help:
 	@echo "Targets:"
@@ -10,6 +10,7 @@ help:
 	@echo "  check-pr-title Validate PR title uses Conventional Commit format"
 	@echo "  check-assets  Block committed images, videos, and asset/media directories"
 	@echo "  check-deprecated-names Block deprecated product names"
+	@echo "  check-github-docs Block legacy/internal branch-model residue in contributor docs"
 	@echo "  check-cjk     Scan for CJK outside the language-policy allowlist (advisory)"
 	@echo "  check-datetime Scan for code that bypasses component/utils/datetime (HARD gate, run via lint)"
 	@echo "  openapi       Regenerate docs/openapi.json from the FastAPI app"
@@ -39,11 +40,13 @@ lint:
 	uv run lint-imports
 	uv run python scripts/check_repo_assets.py
 	uv run python scripts/check_deprecated_names.py
+	uv run python scripts/check_github_contributor_docs.py
 	uv run python scripts/check_datetime_discipline.py
 	uv run python scripts/dump_openapi.py --check
 
 docs-check:
 	python3 scripts/check_docs.py
+	python3 scripts/check_github_contributor_docs.py
 	ruby -e 'require "yaml"; Dir[".github/ISSUE_TEMPLATE/*.yml"].sort.each { |p| YAML.load_file(p); puts "YAML ok: #{p}" }'
 
 check-commits:
@@ -61,6 +64,11 @@ check-assets:
 check-deprecated-names:
 	uv run python scripts/check_deprecated_names.py
 
+# GitHub contributor-doc gate. Public contribution guidance must target the
+# GitHub `main` workflow, not an internal branch model.
+check-github-docs:
+	uv run python scripts/check_github_contributor_docs.py
+
 # Advisory CJK scan (see .claude/rules/language-policy.md). Deliberately NOT
 # wired into `lint` / `ci`: the policy is enforced by review and the rules
 # doc, not a hard gate. Run on demand when touching potentially-CJK files.
diff --git a/scripts/check_github_contributor_docs.py b/scripts/check_github_contributor_docs.py
new file mode 100644
index 000000000..3a500c3d1
--- /dev/null
+++ b/scripts/check_github_contributor_docs.py
@@ -0,0 +1,133 @@
+"""Block legacy/internal branch-model residue in contributor guidance docs."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+MONITORED_FILES = (
+    Path("CLAUDE.md"),
+    Path("CONTRIBUTING.md"),
+    Path("docs/engineering.md"),
+    Path(".github/PULL_REQUEST_TEMPLATE.md"),
+    Path(".claude/skills/commit/SKILL.md"),
+    Path(".claude/skills/new-branch/SKILL.md"),
+    Path(".claude/skills/pr/SKILL.md"),
+)
+
+BRANCH_WORKFLOW_FILES = frozenset(
+    {
+        Path("CLAUDE.md"),
+        Path(".claude/skills/commit/SKILL.md"),
+        Path(".claude/skills/new-branch/SKILL.md"),
+        Path(".claude/skills/pr/SKILL.md"),
+    }
+)
+
+
+@dataclass(frozen=True)
+class Rule:
+    label: str
+    pattern: re.Pattern[str]
+    paths: frozenset[Path] | None = None
+
+
+@dataclass(frozen=True)
+class Violation:
+    path: Path
+    line_number: int
+    label: str
+    text: str
+
+
+_LEGACY_HOSTING = "git" + "lab"
+_LEGACY_STABLE_BRANCH = "mas" + "ter"
+_LEGACY_INTEGRATION_BRANCH = "de" + "v"
+_LEGACY_EMERGENCY_BRANCH = "hot" + "fix"
+_LEGACY_BRANCH_MODEL = "git" + "flow"
+
+RULES = (
+    Rule(
+        "legacy hosting reference",
+        re.compile(rf"\b{_LEGACY_HOSTING}\b", re.IGNORECASE),
+    ),
+    Rule(
+        "legacy review wording",
+        re.compile(r"\bmerge\s+request\b", re.IGNORECASE),
+    ),
+    Rule(
+        "legacy branch model",
+        re.compile(rf"\b{_LEGACY_BRANCH_MODEL}\b", re.IGNORECASE),
+    ),
+    Rule(
+        "legacy stable branch reference",
+        re.compile(rf"\b{_LEGACY_STABLE_BRANCH}\b", re.IGNORECASE),
+    ),
+    Rule(
+        "legacy integration branch reference",
+        re.compile(
+            rf"(?<![A-Za-z]){_LEGACY_INTEGRATION_BRANCH}(?![A-Za-z])",
+            re.IGNORECASE,
+        ),
+        paths=BRANCH_WORKFLOW_FILES,
+    ),
+    Rule(
+        "legacy emergency branch model",
+        re.compile(rf"\b{_LEGACY_EMERGENCY_BRANCH}\b", re.IGNORECASE),
+        paths=BRANCH_WORKFLOW_FILES,
+    ),
+)
+
+
+def find_violations(
+    file_texts: Iterable[tuple[Path, str]],
+) -> list[Violation]:
+    violations: list[Violation] = []
+    for path, text in file_texts:
+        for line_number, line in enumerate(text.splitlines(), start=1):
+            for rule in RULES:
+                if rule.paths is not None and path not in rule.paths:
+                    continue
+                if rule.pattern.search(line):
+                    violations.append(
+                        Violation(
+                            path=path,
+                            line_number=line_number,
+                            label=rule.label,
+                            text=line.strip(),
+                        )
+                    )
+    return violations
+
+
+def _read_monitored_files() -> list[tuple[Path, str]]:
+    return [
+        (path, path.read_text(encoding="utf-8"))
+        for path in MONITORED_FILES
+        if path.exists()
+    ]
+
+
+def main() -> int:
+    violations = find_violations(_read_monitored_files())
+    if not violations:
+        print("GitHub contributor-doc check passed.")
+        return 0
+
+    print(
+        "GitHub contributor-doc check failed.\n"
+        "These files should describe the public GitHub workflow: protected "
+        "`main`, scoped branches, and pull requests back to `main`.\n"
+    )
+    for violation in violations:
+        print(
+            f"- {violation.path}:{violation.line_number}: "
+            f"{violation.label}: {violation.text}"
+        )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tests/unit/test_scripts/test_check_github_contributor_docs.py b/tests/unit/test_scripts/test_check_github_contributor_docs.py
new file mode 100644
index 000000000..0cc0b4704
--- /dev/null
+++ b/tests/unit/test_scripts/test_check_github_contributor_docs.py
@@ -0,0 +1,74 @@
+"""Self-tests for ``scripts/check_github_contributor_docs.py``."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_CHECKER_PATH = _REPO_ROOT / "scripts" / "check_github_contributor_docs.py"
+
+
+def _load_checker():
+    assert _CHECKER_PATH.exists(), "GitHub contributor-doc checker should exist"
+    spec = importlib.util.spec_from_file_location(
+        "_github_contributor_docs_checker", _CHECKER_PATH
+    )
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def test_clean_github_workflow_is_allowed() -> None:
+    checker = _load_checker()
+
+    violations = checker.find_violations(
+        [
+            (
+                Path("CLAUDE.md"),
+                "Create scoped branches from main and open pull requests.\n",
+            )
+        ]
+    )
+
+    assert violations == []
+
+
+def test_legacy_branch_model_terms_are_blocked() -> None:
+    checker = _load_checker()
+    stable_branch = "mas" + "ter"
+    integration_branch = "de" + "v"
+    legacy_review = "merge " + "request"
+    branch_model = "Git" + "Flow"
+    emergency_branch = "hot" + "fix"
+
+    violations = checker.find_violations(
+        [
+            (
+                Path("CLAUDE.md"),
+                f"{stable_branch} is stable and {integration_branch} is integration.\n",
+            ),
+            (Path("CONTRIBUTING.md"), f"Open an internal {legacy_review}.\n"),
+            (
+                Path(".claude/skills/pr/SKILL.md"),
+                f"{branch_model} {emergency_branch} path.\n",
+            ),
+        ]
+    )
+
+    assert [(v.path.as_posix(), v.label) for v in violations] == [
+        ("CLAUDE.md", "legacy stable branch reference"),
+        ("CLAUDE.md", "legacy integration branch reference"),
+        ("CONTRIBUTING.md", "legacy review wording"),
+        (".claude/skills/pr/SKILL.md", "legacy branch model"),
+        (".claude/skills/pr/SKILL.md", "legacy emergency branch model"),
+    ]
+
+
+def test_real_repo_has_no_legacy_contributor_doc_residue() -> None:
+    checker = _load_checker()
+
+    assert checker.main() == 0

From 81c1f8b118d88944e12407a8882c5dff8345948d Mon Sep 17 00:00:00 2001
From: Elliot Chen <cyfyifanchen@gmail.com>
Date: Sat, 27 Jun 2026 12:26:48 +0800
Subject: [PATCH 3/6] docs: record github sync guard

---
 CLAUDE.md           |  7 +++++
 docs/github-sync.md | 77 +++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md       |  1 +
 3 files changed, 85 insertions(+)
 create mode 100644 docs/github-sync.md

diff --git a/CLAUDE.md b/CLAUDE.md
index b0a33eca4..91d48755b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -54,6 +54,13 @@ pull requests back to `main` after the required checks pass.
 See [.claude/skills/new-branch/SKILL.md](.claude/skills/new-branch/SKILL.md)
 for the full branch workflow.
 
+## GitHub sync guard
+
+When refreshing this repository from an internal source archive, preserve
+GitHub-only contributor and automation files. Do not overwrite `CLAUDE.md`,
+`.claude/skills/*`, `CONTRIBUTING.md`, or `.github/*` workflow/template files
+without checking [docs/github-sync.md](docs/github-sync.md).
+
 ## Storage three-piece set
 
 ```
diff --git a/docs/github-sync.md b/docs/github-sync.md
new file mode 100644
index 000000000..3a2aa9cc3
--- /dev/null
+++ b/docs/github-sync.md
@@ -0,0 +1,77 @@
+# GitHub Sync Guard
+
+This page records the GitHub-only files that must be preserved when refreshing
+this public repository from the internal GitLab source/export.
+
+## Rule
+
+When a GitLab export, archive, rsync, or scripted copy is used to refresh the
+GitHub repository, do **not** blindly overwrite GitHub-only contributor,
+automation, and public-facing workflow files.
+
+These files describe the public GitHub workflow: protected `main`, scoped
+branches, GitHub pull requests, GitHub Actions, and community contribution
+rules. Internal workflow text can mislead contributors and AI coding tools if
+it is copied into GitHub.
+
+## Preserve These GitHub Files
+
+Keep the GitHub versions of these files unless a maintainer deliberately updates
+them for the public GitHub workflow:
+
+- `CLAUDE.md`
+- `CONTRIBUTING.md`
+- `.github/PULL_REQUEST_TEMPLATE.md`
+- `.github/BRANCH_PROTECTION.md`
+- `.github/workflows/ci.yml`
+- `.github/workflows/docs.yml`
+- `.github/workflows/commits.yml`
+- `.github/ISSUE_TEMPLATE/**`
+- `.claude/skills/commit/SKILL.md`
+- `.claude/skills/new-branch/SKILL.md`
+- `.claude/skills/pr/SKILL.md`
+- `scripts/check_github_contributor_docs.py`
+- `tests/unit/test_scripts/test_check_github_contributor_docs.py`
+
+## Safe Sync Pattern
+
+Prefer an explicit exclude list in the sync job rather than manual cleanup after
+the overwrite. Example shape:
+
+```bash
+rsync -a --delete \
+  --exclude 'CLAUDE.md' \
+  --exclude 'CONTRIBUTING.md' \
+  --exclude '.github/PULL_REQUEST_TEMPLATE.md' \
+  --exclude '.github/BRANCH_PROTECTION.md' \
+  --exclude '.github/workflows/ci.yml' \
+  --exclude '.github/workflows/docs.yml' \
+  --exclude '.github/workflows/commits.yml' \
+  --exclude '.github/ISSUE_TEMPLATE/' \
+  --exclude '.claude/skills/commit/SKILL.md' \
+  --exclude '.claude/skills/new-branch/SKILL.md' \
+  --exclude '.claude/skills/pr/SKILL.md' \
+  --exclude 'scripts/check_github_contributor_docs.py' \
+  --exclude 'tests/unit/test_scripts/test_check_github_contributor_docs.py' \
+  <gitlab-export>/ <github-checkout>/
+```
+
+After any sync, run:
+
+```bash
+make docs-check
+make lint
+```
+
+The `check_github_contributor_docs.py` gate catches the known failure mode:
+public contributor docs drifting back to an internal branch/review model.
+
+## Review Checklist
+
+Before opening a sync PR:
+
+- Confirm `CLAUDE.md` says branches are created from `main`.
+- Confirm `.claude/skills/pr/SKILL.md` creates PRs with `--base main`.
+- Confirm `CONTRIBUTING.md` says GitHub pull request, not internal review
+  terminology.
+- Confirm `make docs-check` and `make lint` both pass.
diff --git a/docs/index.md b/docs/index.md
index fecd29d72..aab8ed636 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -51,6 +51,7 @@ specific thing (drain a queue, recover from a stuck row, etc.).
 | Doc | Purpose |
 |---|---|
 | [cascade_runbook.md](cascade_runbook.md) | Cascade subsystem ops — drain queue, recover stuck rows |
+| [github-sync.md](github-sync.md) | Guardrails for refreshing GitHub from internal exports without overwriting GitHub-only workflow files |
 | [locomo_benchmark.md](locomo_benchmark.md) | LoCoMo benchmark — run and evaluate |
 
 ## Engineering

From 869fa85f2202817e71725b52d76122e83b69cf4a Mon Sep 17 00:00:00 2001
From: Elliot Chen <cyfyifanchen@gmail.com>
Date: Sat, 27 Jun 2026 14:26:53 +0800
Subject: [PATCH 4/6] chore: retrigger commit lint


From c078677e2392bfff8c4d93df5e9a4face93510ba Mon Sep 17 00:00:00 2001
From: Elliot Chen <cyfyifanchen@gmail.com>
Date: Sun, 28 Jun 2026 07:24:46 +0800
Subject: [PATCH 5/6] docs: leave readme files unchanged

---
 README.md           | 69 +++++++++++++++-------------------
 README.zh-CN.md     | 91 +++++++++++++++++++--------------------------
 use-cases/README.md |  2 +-
 3 files changed, 70 insertions(+), 92 deletions(-)

diff --git a/README.md b/README.md
index 3e5ea97bc..7f221d8b7 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,6 @@
 <div align="center" id="readme-top">
 
-<h1 align="center">EverOS</h1>
-
-<p align="center"><strong>Local-first memory for AI agents, stored as Markdown.</strong></p>
-
-<p align="center">Markdown source of truth · SQLite + LanceDB · User + agent memory · Knowledge + Reflection</p>
+![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)
 
 <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>
@@ -25,7 +21,7 @@
 
 <br>
 
-- [Why EverOS](#why-everos)
+- [Why Ever OS](#why-ever-os)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
 - [Documentation](#documentation)
@@ -38,13 +34,13 @@
 </details>
 
 
-## Why EverOS
+## Why Ever OS
 
-EverOS is a 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 retrieval,
-search, and background memory evolution.
+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.
 
 <table>
 <tr>
@@ -103,13 +99,13 @@ search, and background memory evolution.
 - To run the real server-backed memory flow, create two provider keys before
   `everos init`:
 
-| Capability | Provider path | Used for | Configure in `everos.toml` |
+| Capability | Provider | Used for | Fill these `.env` slots |
 | --- | --- | --- | --- |
-| Chat + multimodal | Any OpenAI-compatible LLM endpoint, such as [OpenRouter](https://openrouter.ai/) or OpenAI | `LLM` / `MULTIMODAL` | `[llm]` and `[multimodal]` `api_key`, `base_url`, and model fields |
-| Embedding + rerank | OpenAI-compatible embeddings plus DeepInfra / vLLM / DashScope rerank | `EMBEDDING` / `RERANK` | `[embedding]` and `[rerank]` `api_key`, `base_url`, and model fields |
+| 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 also override any TOML field with the matching environment variable,
-for example `EVEROS_LLM__BASE_URL` or `EVEROS_EMBEDDING__API_KEY`.
+You can use other OpenAI-compatible providers by changing the matching
+`*__BASE_URL` fields in `.env`.
 
 ### 1. Install
 
@@ -155,17 +151,19 @@ everos demo --plain
 
 ### 3. Configure
 
-Generate starter TOML files, then fill in provider credentials and endpoints in
-`~/.everos/everos.toml`. The second file, `ome.toml`, controls the offline
-memory engine schedule.
+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 `~/.everos/everos.toml` and `~/.everos/ome.toml` by
-default. Use `everos init --root /path/to/everos` to choose another memory
-root.
+`everos init` writes `./.env` by default. Use `everos init --xdg` to
+write `${XDG_CONFIG_HOME:-~/.config}/everos/.env` instead.
 
 ### 4. Start EverOS
 
@@ -185,10 +183,11 @@ Expected response:
 {"status":"ok"}
 ```
 
-`everos server start` reads `<root>/everos.toml` and exits if the file is
-missing. The endpoint stack is OpenAI-protocol compatible; set each provider's
-`base_url` in TOML, or override it with `EVEROS_*__BASE_URL` environment
-variables for containers and CI.
+`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:
 
@@ -269,8 +268,8 @@ 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
-(`[multimodal]` in `everos.toml`, or `EVEROS_MULTIMODAL__*` environment
-overrides).
+(`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
@@ -294,7 +293,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                          # create ~/.everos/everos.toml + ome.toml
+everos init                          # paste OpenRouter + DeepInfra keys into .env
 
 everos --help
 make test
@@ -466,7 +465,7 @@ Ruminer brings persistent memory to a browser agent so it can carry personal con
 
 #### EverMem Sync With EverOS
 
-One command to connect any AI coding CLI to EverOS long-term memory.
+One command to connect any AI coding CLI to EverMemOS long-term memory.
 
 [Code](https://github.com/nanxingw/EverMem)
 
@@ -642,14 +641,6 @@ Explore stored entities and relationships in a graph interface. Frontend demo; b
 
 ## Documentation
 
-- [docs/index.md](docs/index.md) — Documentation map
-- [QUICKSTART.md](QUICKSTART.md) — Five-minute service + memory walkthrough
-- [docs/overview.md](docs/overview.md) — Project vision, scope, and design philosophy
-- [docs/positioning.md](docs/positioning.md) — Public GTM language, banner direction, and competitor framing
-- [docs/configuration.md](docs/configuration.md) — TOML and environment-variable configuration reference
-- [docs/api.md](docs/api.md) — HTTP API v1 reference
-- [docs/knowledge.md](docs/knowledge.md) — Knowledge base module
-- [docs/reflection.md](docs/reflection.md) — Offline memory consolidation
 - [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
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 01dcc9097..b7a899e9c 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,10 +1,6 @@
 <div align="center" id="readme-top">
 
-<h1 align="center">EverOS</h1>
-
-<p align="center"><strong>面向 AI agents 的 local-first Markdown 记忆运行时。</strong></p>
-
-<p align="center">Markdown source of truth · SQLite + LanceDB · 用户 + Agent 双轨记忆 · Knowledge + Reflection</p>
+![EverOS banner](https://github.com/user-attachments/assets/8e217d39-5d15-4c6c-9b54-3e83add4e0f2)
 
 <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>
@@ -40,11 +36,11 @@
 
 ## 为什么选择 EverOS
 
-EverOS 是面向 agents 和 makers 的 local-first memory runtime。它从 day
-one 开始就提供一层可携带的记忆层，让记忆穿过 coding assistants、apps、
-devices 和 workflows。它会把 conversations、files 和 agent trajectories
-保存为可读 Markdown，并同步本地 SQLite 与 LanceDB 索引，用于检索、搜索
-和后台记忆进化。
+EverOS 是面向 agents 和 makers 的 Python library 与 local-first memory
+runtime。它从 day one 开始就提供一层可携带的记忆层，让记忆穿过 coding
+assistants、apps、devices 和 workflows。它会把 conversations、files 和
+agent trajectories 保存为可读 Markdown，并同步本地 SQLite 与 LanceDB
+索引，用于快速检索和自进化复用。
 
 <table>
 <tr>
@@ -104,14 +100,14 @@ devices 和 workflows。它会把 conversations、files 和 agent trajectories
   [阿里云百炼控制台](https://bailian.console.aliyun.com/) 创建一个
   DashScope API Key：
 
-| 能力 | 默认 Provider | 用途 | 配置到 `everos.toml` |
+| 能力 | 默认 Provider | 用途 | 填入这些 `.env` 字段 |
 | --- | --- | --- | --- |
-| Chat / extraction | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `LLM` | `[llm]` 的 `model`、`api_key`、`base_url` |
-| Embedding | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `EMBEDDING` | `[embedding]` 的 `model`、`api_key`、`base_url` |
-| Re-rank | [阿里云百炼 / DashScope](https://bailian.console.aliyun.com/) | `RERANK` | `[rerank]` 的 `provider`、`model`、`api_key`、`base_url` |
+| 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 可以填到这三个 section。多模态文件摄取仍通过
-`[multimodal]` 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。
+同一个 DashScope API Key 可以填到这三个 slot。多模态文件摄取仍通过
+`EVEROS_MULTIMODAL__*` 单独配置；如果只跑下面的文本记忆闭环，不需要先配置它。
 
 ### 1. 安装
 
@@ -156,36 +152,34 @@ everos demo --plain
 
 ### 3. 配置
 
-生成 starter TOML 文件，然后在 `~/.everos/everos.toml` 中填入模型、
-endpoint 和 API key。中文 quick start 默认推荐使用
+生成一个 starter `.env` 文件，然后根据生成的注释填入对应的 API key 字段。
+中文 quick start 默认推荐使用
 [阿里云百炼控制台](https://bailian.console.aliyun.com/) 的 DashScope API Key
 配置 `LLM` / `EMBEDDING` / `RERANK` 三个核心能力。
 
 ```bash
 everos init
+# or, from a source checkout:
+cp .env.example .env
 ```
 
-`everos init` 默认写入 `~/.everos/everos.toml` 和 `~/.everos/ome.toml`。
-也可以使用 `everos init --root /path/to/everos` 指定 memory root。
+`everos init` 默认写入 `./.env`。也可以使用 `everos init --xdg`
+写入 `${XDG_CONFIG_HOME:-~/.config}/everos/.env`。
 
 百炼三件套示例：
 
-```toml
-[llm]
-model = "qwen-plus"
-api_key = "<DASHSCOPE_API_KEY>"
-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"
-
-[rerank]
-provider = "dashscope"
-model = "gte-rerank-v2"
-api_key = "<DASHSCOPE_API_KEY>"
-base_url = "https://dashscope.aliyuncs.com"
+```env
+EVEROS_LLM__MODEL=qwen-plus
+EVEROS_LLM__API_KEY=<DASHSCOPE_API_KEY>
+EVEROS_LLM__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
+
+EVEROS_RERANK__MODEL=gte-rerank-v2
+EVEROS_RERANK__API_KEY=<DASHSCOPE_API_KEY>
+EVEROS_RERANK__BASE_URL=https://dashscope.aliyuncs.com
 ```
 
 ### 4. 启动 EverOS
@@ -206,10 +200,11 @@ curl http://127.0.0.1:8000/health
 {"status":"ok"}
 ```
 
-`everos server start` 会读取 `<root>/everos.toml`；如果文件不存在，会提示先
-运行 `everos init`。端点栈兼容 OpenAI protocol。你可以在 TOML 中设置各
-provider 的 `base_url`，也可以用 `EVEROS_*__BASE_URL` 环境变量覆盖，方便
-container 和 CI 使用。
+`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 里运行：
 
@@ -285,8 +280,8 @@ uv pip install 'everos[multimodal]'   # or: pip install 'everos[multimodal]'
 ```
 
 这会引入 `everalgo-parser`（包含用于 SVG 支持的 `[svg]` bundle，通过
-cairosvg）并接入多模态 LLM client（`everos.toml` 中的 `[multimodal]`
-section，或 `EVEROS_MULTIMODAL__*` 环境变量覆盖）。
+cairosvg）并接入多模态 LLM client（`.env` 中的 `EVEROS_MULTIMODAL__*`
+字段，默认通过 OpenRouter 使用 `google/gemini-3-flash-preview`）。
 
 **Office 文档支持需要 LibreOffice 作为系统依赖。** parser 会调用
 `soffice`（LibreOffice 的 headless renderer），先把 `.doc` / `.docx` /
@@ -309,7 +304,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                          # 创建 ~/.everos/everos.toml + ome.toml
+everos init                          # 把百炼 DashScope API Key 填进 .env
 
 everos --help
 make test
@@ -479,7 +474,7 @@ Ruminer 为 browser agent 带来持久记忆，让它能在不同网页任务之
 
 #### EverMem 与 EverOS 同步
 
-一条命令，把任意 AI coding CLI 连接到 EverOS 长期记忆。
+一条命令，把任意 AI coding CLI 连接到 EverMemOS 长期记忆。
 
 [代码](https://github.com/nanxingw/EverMem)
 
@@ -655,14 +650,6 @@ Claude Code 的持久记忆插件。自动保存并回忆过去 coding sessions
 
 ## 文档
 
-- [docs/index.md](docs/index.md) - 文档地图
-- [QUICKSTART.md](QUICKSTART.md) - 5 分钟 service + memory walkthrough
-- [docs/overview.md](docs/overview.md) - 项目愿景、范围与设计哲学
-- [docs/positioning.md](docs/positioning.md) - GTM 文案、banner 方向与竞品 framing
-- [docs/configuration.md](docs/configuration.md) - TOML 与环境变量配置参考
-- [docs/api.md](docs/api.md) - HTTP API v1 参考
-- [docs/knowledge.md](docs/knowledge.md) - Knowledge base 模块
-- [docs/reflection.md](docs/reflection.md) - 离线记忆 consolidation
 - [docs/everos-demo.md](docs/everos-demo.md) - Demo 范围与 TUI 源码布局
 - [docs/how-memory-works.md](docs/how-memory-works.md) - Markdown、SQLite、LanceDB 与 recall flow
 - [docs/use-cases.md](docs/use-cases.md) - 完整使用场景 gallery 和集成示例
diff --git a/use-cases/README.md b/use-cases/README.md
index 8bfb03dca..88c52e82f 100644
--- a/use-cases/README.md
+++ b/use-cases/README.md
@@ -145,7 +145,7 @@ Ruminer brings persistent memory to a browser agent so it can carry personal con
 
 #### EverMem Sync with EverOS
 
-One command to connect any AI coding CLI to EverOS long-term memory.
+One command to connect any AI coding CLI to EverMemOS long-term memory.
 
 [Code](https://github.com/nanxingw/EverMem)
 

From d7edc6d1794cf5264cd220490205a76d49af54f0 Mon Sep 17 00:00:00 2001
From: Elliot Chen <cyfyifanchen@gmail.com>
Date: Sun, 28 Jun 2026 07:53:27 +0800
Subject: [PATCH 6/6] docs: remove public positioning comparison

---
 docs/index.md       |  1 -
 docs/positioning.md | 73 ---------------------------------------------
 2 files changed, 74 deletions(-)
 delete mode 100644 docs/positioning.md

diff --git a/docs/index.md b/docs/index.md
index aab8ed636..367df8cd3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -38,7 +38,6 @@ why the system is shaped the way it is.
 | Doc | Purpose |
 |---|---|
 | [overview.md](overview.md) | Project vision, scope, design philosophy |
-| [positioning.md](positioning.md) | Public GTM language, proof points, banner direction, and competitor framing |
 | [how-memory-works.md](how-memory-works.md) | Storage stack + on-disk paths + write→index→read pipeline + consistency |
 | [architecture.md](architecture.md) | DDD layered architecture + dependency rules |
 | [datetime.md](datetime.md) | Two-zone discipline — UTC at storage, display tz at boundaries |
diff --git a/docs/positioning.md b/docs/positioning.md
deleted file mode 100644
index 705d4f862..000000000
--- a/docs/positioning.md
+++ /dev/null
@@ -1,73 +0,0 @@
-# Positioning
-
-This page keeps EverOS public language consistent across the README, docs,
-release notes, banners, and demos.
-
-## Category
-
-EverOS is a **local-first memory runtime for AI agents**.
-
-Use this category when the audience cares about agent infrastructure,
-developer tools, and local data ownership. Avoid positioning EverOS as only a
-vector database, RAG library, chat-history SDK, or dashboard.
-
-## One-Liner
-
-EverOS gives agents long-term memory stored as readable Markdown, with local
-SQLite and LanceDB indexes rebuilt from that source of truth.
-
-## Primary Proof Points
-
-- Markdown source of truth: readable, editable, diffable, and Git-versioned.
-- Local runtime stack: Markdown + SQLite + LanceDB, no required hosted database.
-- User + agent memory tracks: user episodes/profile and agent cases/skills are
-  separate first-class surfaces.
-- Knowledge + Reflection: source-backed knowledge pages and offline memory
-  consolidation extend beyond retrieval-only memory.
-- Rebuildable indexes: derived SQLite and LanceDB state can be regenerated from
-  the Markdown files.
-
-## Claims To Avoid Without Fresh Evidence
-
-Do not use benchmark or research claims in public hero copy unless they link to
-an owned benchmark or citation page in this repository.
-
-Avoid unsupported claims such as:
-
-- Exact LoCoMo accuracy numbers.
-- Exact p95 latency numbers.
-- Exact token-savings percentages.
-- Paper counts or publication claims.
-- "Best", "fastest", or "most accurate" market-wide comparisons.
-
-Use capability language instead:
-
-- "Local-first memory for AI agents, stored as Markdown."
-- "Memory agents can read, edit, search, and evolve."
-- "A Markdown-native memory runtime for AI agents."
-
-## Comparison Notes
-
-These notes are for maintainers writing public copy. Keep comparisons factual,
-linked, and framed around fit rather than winner-takes-all claims.
-
-| Project | Public positioning | EverOS distinction |
-|---|---|---|
-| [Mem0](https://github.com/mem0ai/mem0) | Universal memory layer with SDKs, CLI, integrations, self-hosted server, and managed platform paths. | Position EverOS around local-first ownership, Markdown source files, direct file editing, and rebuildable local indexes. |
-| [MemOS](https://github.com/MemTensor/MemOS) | Memory OS / memory-augmented generation system for persistent memory, hybrid retrieval, and cross-task skill reuse. | Position EverOS as the practical local runtime with a concrete Markdown + SQLite + LanceDB storage model rather than a broad memory-OS taxonomy. |
-| [OpenViking](https://github.com/volcengine/OpenViking) | Context database for AI agents using a filesystem paradigm for context, memory, resources, and skills. | Position EverOS around memory extraction, Markdown source of truth, Knowledge, Reflection, and derived indexes, not just context storage. |
-| [MemPalace](https://github.com/MemPalace/mempalace) | Personal memory OS for agents and developers, with local-first and integration-oriented workflows. | Position EverOS around typed storage boundaries, source-backed Markdown, tested cascade/index rebuilds, and first-class user + agent memory tracks. |
-
-## Banner Direction
-
-Prefer a capability-led banner over metric-led copy:
-
-```text
-EverOS
-Local-first memory for AI agents, stored as Markdown.
-Markdown source of truth · SQLite + LanceDB · User + agent memory · Knowledge + Reflection
-```
-
-When metrics are available, link the banner or README badge to the benchmark
-page that explains model stack, dataset, hardware, sample size, and command to
-reproduce the result.