docs: document EverOS 1.0.0 issue migration (#258)

* docs: document EverOS 1.0 issue migration

* docs: standardize EverOS 1.0.0 wording

.github/BRANCH_PROTECTION.md

@@ -1,6 +1,6 @@
 # Branch Protection Baseline
 
-Use this as the admin checklist for `main` after the EverOS 1.0 history reset.
+Use this as the admin checklist for `main` after the EverOS 1.0.0 history reset.
 
 ## Required Repository Rule
 

README.md

@@ -200,6 +200,7 @@ everos/                        # repo root
 - [docs/overview.md](docs/overview.md) — Project overview & vision
 - [docs/architecture.md](docs/architecture.md) — DDD layered architecture & dependency rules
 - [docs/engineering.md](docs/engineering.md) — Engineering & dev-efficiency infrastructure (CI / tooling / Claude Code)
+- [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) — Legacy API and infrastructure migration notes
 - [CHANGELOG.md](CHANGELOG.md) — Release notes
 - [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute
 - [.claude/rules/](.claude/rules/) — Detailed coding conventions (auto-loaded by Claude Code)
@@ -437,13 +438,13 @@ A context-native AI wearable that listens to everyday life and converts conversa
 <tr>
 <td width="50%" valign="top">
 
-[![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc)](https://github.com/EverMind-AI/EverOS/tree/0f49826ba0f9a94e1974c97614a46a68e0a08b52/evermemos-openclaw-plugin)
+[![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc)](docs/migration-to-1.0.0.md)
 
-#### OpenClaw Agent Memory
+#### Legacy OpenClaw Agent Memory
 
-A 24/7 agent workflow with continuous learning memory across sessions.
+Archived pre-1.0.0 plugin reference. New integrations should use the EverOS 1.0.0 API.
 
-[Plugin](https://github.com/EverMind-AI/EverOS/tree/0f49826ba0f9a94e1974c97614a46a68e0a08b52/evermemos-openclaw-plugin)
+[Learn more](docs/migration-to-1.0.0.md)
 
 </td>
 <td width="50%" valign="top">

docs/index.md

@@ -15,6 +15,7 @@ already know what you want to do and need to know exactly how.
 | [cli.md](cli.md) | `everos` CLI subcommands + env var conventions |
 | [storage_layout.md](storage_layout.md) | Memory-root tree + frontmatter chassis + EntryId encoding |
 | [prompt_slots.md](prompt_slots.md) | YamlConfigLoader + three-layer prompt override |
+| [migration-to-1.0.0.md](migration-to-1.0.0.md) | Legacy API and infrastructure migration notes for EverOS 1.0.0 |
 
 ## Explanation
 

docs/migration-to-1.0.0.md

@@ -0,0 +1,67 @@
+# EverOS 1.0.0 Migration Notes
+
+EverOS 1.0.0 is a fresh architecture. Historical issues, examples, and
+plugins may reference APIs and infrastructure that no longer exist in
+the current open-source repository.
+
+## Current 1.0.0 Contract
+
+The supported local OSS HTTP API lives under:
+
+```text
+POST /api/v1/memory/add
+POST /api/v1/memory/flush
+POST /api/v1/memory/search
+POST /api/v1/memory/get
+```
+
+Use [api.md](api.md) for the canonical request and response schemas.
+
+The storage stack is:
+
+```text
+Markdown files + SQLite + LanceDB
+```
+
+MongoDB, Elasticsearch, Milvus, Redis, Kafka, longjob workers, and the
+old Docker Compose stack are not part of EverOS 1.0.0.
+
+## Legacy API Mapping
+
+These pre-1.0.0 routes are no longer supported by the OSS repo:
+
+| Legacy route | EverOS 1.0.0 replacement |
+|---|---|
+| `POST /api/v1/memories` | `POST /api/v1/memory/add` |
+| `POST /api/v1/memories/group` | `POST /api/v1/memory/add` with `app_id` / `project_id` scoping |
+| `GET /api/v1/memories/search` | `POST /api/v1/memory/search` |
+| `POST /api/v1/memories/search` | `POST /api/v1/memory/search` |
+| `GET /api/v1/memories` | `POST /api/v1/memory/get` |
+| `POST /api/v1/memories/get` | `POST /api/v1/memory/get` |
+| `/api/v3/agentic/*` | `POST /api/v1/memory/*` |
+
+The 1.0.0 API also changed memory type names. For example,
+`episodic_memory` is now `episode` in `/get`; `/search` returns typed
+arrays such as `episodes`, `profiles`, `agent_cases`, and
+`agent_skills`.
+
+## Integration Guidance
+
+For new integrations:
+
+- Batch messages into one `/api/v1/memory/add` request instead of
+  sending one flat message object per HTTP call.
+- Use `/flush` when a demo or test needs immediate extraction.
+- Use `/search` for ranked recall and `/get` for paginated browsing.
+- Treat old OpenClaw and EverMem Cloud plugin examples as archived
+  references unless they have been explicitly updated to the 1.0.0 API.
+
+## Benchmark Guidance
+
+The current LoCoMo reproduction path is documented in
+[locomo_benchmark.md](locomo_benchmark.md). The benchmark driver uses
+the 1.0.0 server API: add, flush, search, answer, and evaluate.
+
+Old HyperMem / pre-1.0.0 evaluation pipeline reports should not be used
+as 1.0.0 bug reports unless they can be reproduced with the current
+benchmark commands.

scripts/check_deprecated_names.py

@@ -4,9 +4,9 @@ from __future__ import annotations
 
 import re
 import subprocess
+from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Iterable
 
 DEPRECATED_NAME_RE = re.compile(r"\bever[\s_-]*core\b", flags=re.IGNORECASE)
 SKIP_SUFFIXES = frozenset(
@@ -53,11 +53,7 @@ def _tracked_paths() -> list[Path]:
         stdout=subprocess.PIPE,
         text=False,
     )
-    return [
+    return [Path(raw.decode("utf-8")) for raw in result.stdout.split(b"\0") if raw]
-        Path(raw.decode("utf-8"))
-        for raw in result.stdout.split(b"\0")
-        if raw
-    ]
 
 
 def _tracked_text_files() -> Iterable[tuple[str, str]]:

use-cases/README.md

@@ -229,13 +229,13 @@ A context-native AI wearable that listens to everyday life and converts conversa
 <tr>
 <td width="50%" valign="top">
 
-[![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc)](https://github.com/EverMind-AI/EverOS/tree/0f49826ba0f9a94e1974c97614a46a68e0a08b52/evermemos-openclaw-plugin)
+[![banner-gif](https://github.com/user-attachments/assets/df9677ec-386f-4c56-a428-08bca25c54dc)](../docs/migration-to-1.0.0.md)
 
-#### OpenClaw Agent Memory
+#### Legacy OpenClaw Agent Memory
 
-A 24/7 agent workflow with continuous learning memory across sessions.
+Archived pre-1.0.0 plugin reference. New integrations should use the EverOS 1.0.0 API.
 
-[Plugin](https://github.com/EverMind-AI/EverOS/tree/0f49826ba0f9a94e1974c97614a46a68e0a08b52/evermemos-openclaw-plugin)
+[Learn more](../docs/migration-to-1.0.0.md)
 
 </td>
 <td width="50%" valign="top">

use-cases/claude-code-plugin/README.md

@@ -2,6 +2,13 @@
 
 Persistent memory for Claude Code. Automatically saves and recalls context from past coding sessions.
 
+> Compatibility note: this folder documents a legacy EverMem Cloud
+> plugin. It still uses the old cloud `/api/v1/memories/*` routes and
+> should not be treated as the canonical local EverOS 1.0.0 OSS API.
+> New integrations should follow
+> [EverOS 1.0.0 migration notes](../../docs/migration-to-1.0.0.md) and
+> [the API reference](../../docs/api.md).
+
 ![Memory Hub Screenshot](https://github.com/user-attachments/assets/af37c1f6-7ba5-430c-b99d-2a7e7eac618f)
 
 ## Features