doc(reme): add design philosophy part to reme concepts for advocating

README.md

@@ -1,72 +1,71 @@
 # AgentScope Documentation
 
-This repository contains the official documentation for [AgentScope](https://github.com/modelscope/agentscope), a production-ready, multi-agent framework for building LLM-empowered agent applications. The docs site is built with [Mintlify](https://mintlify.com).
+This repository contains the unified documentation site for [AgentScope](https://github.com/agentscope-ai/agentscope) and [ReMe](https://github.com/agentscope-ai/ReMe). The site is built with [Mintlify](https://mintlify.com) and deployed at [docs.agentscope.io](https://docs.agentscope.io).
 
-## Overview
+## Documentation Sets
 
-AgentScope provides a simple yet efficient way to build LLM-empowered agent applications, with built-in support for:
+- **AgentScope**: a framework for building agent applications.
+- **ReMe**: a local-first, file-native memory layer for AI agents.
 
-- Multi-agent orchestration
-- Multiple model providers (DashScope, Gemini, OpenAI, Anthropic, Ollama)
-- Memory (short-term and long-term)
-- Tools and RAG
-- Observability and evaluation
+Each project owns its version history and bilingual navigation. Version selectors are defined independently for the `AgentScope` and `ReMe` tabs in `docs.json`.
 
-## Development
+## Local Development
 
-### Prerequisites
-
-- Node.js version 19 or higher
-
-### Local Preview
+Use an active Node.js LTS release (Node 20 or 22).
 
 Install the [Mintlify CLI](https://www.npmjs.com/package/mint):
 
 ```bash
 npm i -g mint
 ```
 
-Start the local development server at the root of this repository (where `docs.json` is located):
+From the repository root, validate the site or start a preview:
 
 ```bash
+mint validate
 mint dev
 ```
 
-View your local preview at `http://localhost:3000`.
+The preview is available at `http://localhost:3000` by default.
 
 ## Repository Structure
 
-```
+```text
 .
-├── basic-concepts/       # Core AgentScope concepts (msg, agent, model, memory, tool)
-├── building-blocks/      # Advanced building blocks
-├── tutorial/             # Step-by-step tutorials
-├── out-of-box-agents/    # Pre-built agents
-├── api-reference/        # API documentation
-├── observe-and-evaluate/ # Monitoring and evaluation
-├── tune-agent/           # Agent tuning guides
-├── deploy-and-serve/     # Deployment options
-├── essentials/           # Documentation components
-├── others/               # FAQ and additional resources
-└── docs.json             # Mintlify navigation config
+├── agentscope/
+│   └── <version>/{en,zh}/   # Versioned AgentScope documentation
+├── reme/
+│   └── <version>/{en,zh}/   # Versioned ReMe documentation
+├── images/                  # Shared static assets
+├── scripts/                 # Documentation maintenance scripts
+├── docs.json                # Mintlify navigation and redirects
+└── CLAUDE.md                # Writing and review guidelines
 ```
 
-## Contributing
+## Version Management
 
-When adding or updating documentation:
+Published documentation is immutable within its version directory. For a new release:
 
-1. Place `.mdx` files in the appropriate directory
-2. Update `docs.json` to include new pages in the navigation
-3. Start every page with YAML frontmatter (`title` and `description`)
-4. Follow the [writing style guidelines](CLAUDE.md) in this repo
-5. Preview changes locally before submitting a PR
+1. Copy the latest relevant version into a new project version directory.
+2. Update every version-specific internal link in the copied pages.
+3. Add the version under the matching project tab for both languages in `docs.json`.
+4. Point that project's `latest` or `stable` redirect at the new version.
+5. Run `mint validate` before submitting the change.
 
-## Troubleshooting
+AgentScope versions can be created with `scripts/create-version.sh`. ReMe follows the same directory and navigation model under `reme/` and uses project-scoped aliases such as `/reme/stable/...` so its releases do not affect AgentScope aliases.
+
+## Contributing
+
+When adding or updating documentation:
 
-- **Dev server not running**: Run `mint update` to get the latest CLI version.
-- **Page shows 404**: Ensure you are running in the folder containing `docs.json`.
+1. Place `.mdx` files in the correct project, version, and language directory.
+2. Update `docs.json` when pages or versions change.
+3. Start every page with YAML frontmatter containing `title` and `description`.
+4. Follow [CLAUDE.md](CLAUDE.md) for writing and review conventions.
+5. Run `mint validate` before submitting a pull request.
 
 ## Resources
 
 - [AgentScope GitHub](https://github.com/agentscope-ai/agentscope)
+- [ReMe GitHub](https://github.com/agentscope-ai/ReMe)
 - [Mintlify Documentation](https://mintlify.com/docs)

versions/1.0.21/en/basic-concepts/context-and-memory.mdx → agentscope/1.0.21/en/basic-concepts/context-and-memory.mdx

@@ -7,7 +7,7 @@ icon: 'database'
 This document introduces how AgentScope handles context and memory in agent workflows.
 
 <Info>
-For implementation details and APIs, see [Context and Memory](/versions/1.0.21/en/building-blocks/context-and-memory).
+For implementation details and APIs, see [Context and Memory](/agentscope/1.0.21/en/building-blocks/context-and-memory).
 </Info>
 
 ---

versions/1.0.21/en/basic-concepts/model.mdx → agentscope/1.0.21/en/basic-concepts/model.mdx

@@ -45,7 +45,7 @@ To support multi-agent conversations in a chatbot format, AgentScope designs a f
 Such formatters are distinguished by the suffix `ChatFormatter` (e.g., `DashScopeChatFormatter`) and `MultiAgentFormatter` (e.g., `DashScopeMultiAgentFormatter`) — the former is for two-party conversations (user + assistant), while the latter is for multi-agent conversations.
 
 <Tip>
-For detailed usage examples and a full provider reference table mapping each model class to its corresponding formatter, see [Models](/versions/1.0.21/en/building-blocks/models).
+For detailed usage examples and a full provider reference table mapping each model class to its corresponding formatter, see [Models](/agentscope/1.0.21/en/building-blocks/models).
 </Tip>
 
 

versions/1.0.21/en/building-blocks/agent.mdx → agentscope/1.0.21/en/building-blocks/agent.mdx

@@ -39,7 +39,7 @@ AgentScope provides several built-in agent types to cover different use cases. U
 | Memory compression | Automatically compress long conversation history |
 | Parallel tool calls | Execute multiple tool calls concurrently |
 | Structured output | Return typed, schema-validated responses |
-| Fine-grained MCP control | See [MCP integration](/versions/1.0.21/en/building-blocks/tool-capabilities#mcp-integration) |
+| Fine-grained MCP control | See [MCP integration](/agentscope/1.0.21/en/building-blocks/tool-capabilities#mcp-integration) |
 | Meta tool | Agent-controlled tool management |
 | Long-term memory | Self-controlled persistent memory |
 | Plan | Break complex tasks into managed subtasks and execute them systematically |

versions/1.0.21/en/building-blocks/context-and-memory.mdx → agentscope/1.0.21/en/building-blocks/context-and-memory.mdx

@@ -19,7 +19,7 @@ This mechanism supports high-level memory management in agents. For example, in
 The memory module focuses on storage and management. Algorithmic logic (for example, compression strategy) is implemented at the agent layer.
 </Note>
 
-> For conceptual background, see [Context and Memory](/versions/1.0.21/en/basic-concepts/context-and-memory).
+> For conceptual background, see [Context and Memory](/agentscope/1.0.21/en/basic-concepts/context-and-memory).
 
 In AgentScope, memory can be viewed in two layers:
 
@@ -442,10 +442,10 @@ If your backend supports all methods, it can be used in `both` mode.
 ## Further Reading
 
 <CardGroup cols={2}>
-  <Card title="Agent" icon="user-robot" href="/versions/1.0.21/en/basic-concepts/agent">
+  <Card title="Agent" icon="user-robot" href="/agentscope/1.0.21/en/basic-concepts/agent">
     Understand the agent's core methods and the ReAct paradigm.
   </Card>
-  <Card title="Tool" icon="wrench" href="/versions/1.0.21/en/basic-concepts/tool">
+  <Card title="Tool" icon="wrench" href="/agentscope/1.0.21/en/basic-concepts/tool">
     Learn how to extend agents with native functions, MCP, and skills.
   </Card>
 </CardGroup>

versions/1.0.21/en/building-blocks/models.mdx → agentscope/1.0.21/en/building-blocks/models.mdx

@@ -22,7 +22,7 @@ This document covers detailed usage examples and provider-specific references fo
 </CardGroup>
 
 <Info>
-For core concepts and design principles, see [Model](/versions/1.0.21/en/basic-concepts/model). For details on `Msg` and content blocks, see [Msg](/versions/1.0.21/en/basic-concepts/msg).
+For core concepts and design principles, see [Model](/agentscope/1.0.21/en/basic-concepts/model). For details on `Msg` and content blocks, see [Msg](/agentscope/1.0.21/en/basic-concepts/msg).
 </Info>
 
 ---
@@ -236,7 +236,7 @@ The `tool_choice` parameter controls invocation behavior:
 - `"<function_name>"`: Force a specific tool
 
 <Tip>
-Use the `Toolkit` class to auto-generate JSON schemas from Python functions with docstrings. See [Tool](/versions/1.0.21/en/basic-concepts/tool) for details.
+Use the `Toolkit` class to auto-generate JSON schemas from Python functions with docstrings. See [Tool](/agentscope/1.0.21/en/basic-concepts/tool) for details.
 </Tip>
 
 ### Provider Reference

versions/1.0.21/en/building-blocks/orchestration.mdx → agentscope/1.0.21/en/building-blocks/orchestration.mdx

@@ -388,7 +388,7 @@ await chat_room.stop()                  # Disconnect all agents
 
 ## Formatter Reference
 
-> For an introduction to Chat vs MultiAgent formatters and how to choose one, see [Model — Formatter](/versions/1.0.21/en/basic-concepts/model#chat-model).
+> For an introduction to Chat vs MultiAgent formatters and how to choose one, see [Model — Formatter](/agentscope/1.0.21/en/basic-concepts/model#chat-model).
 
 ### Formatter Table
 

versions/1.0.21/en/building-blocks/rag.mdx → agentscope/1.0.21/en/building-blocks/rag.mdx

@@ -318,10 +318,10 @@ asyncio.run(example_multimodal_rag())
 ## Further Reading
 
 <CardGroup cols={2}>
-  <Card title="Context and Memory" icon="memory" href="/versions/1.0.21/en/building-blocks/context-and-memory">
+  <Card title="Context and Memory" icon="memory" href="/agentscope/1.0.21/en/building-blocks/context-and-memory">
     Memory backends for storing and managing session messages.
   </Card>
-  <Card title="Agent" icon="user-robot" href="/versions/1.0.21/en/building-blocks/agent">
+  <Card title="Agent" icon="user-robot" href="/agentscope/1.0.21/en/building-blocks/agent">
     ReActAgent internals, tool registration, and reply lifecycle.
   </Card>
 </CardGroup>

versions/1.0.21/en/index.mdx → agentscope/1.0.21/en/index.mdx

@@ -15,11 +15,11 @@ We design for increasingly agentic LLMs. Our approach leverages the models' reas
 
 ## Start with AgentScope
 
-* [Quickstart ->](/versions/1.0.21/quickstart): Build your first chatbot agent in 5 minutes
-* [Out-of-box agents ->](/versions/1.0.21/out-of-box-agents): Try out our collection of pre-built agents for various use cases
-* [Basic concepts & building blocks ->](/versions/1.0.21/basic-concepts): Learn about the core abstractions in AgentScope and how to use them
-* [Observe & evaluate ->](/versions/1.0.21/observe-and-evaluate): Learn how to observe and evaluate your agents with built-in OTel support and evaluation tools
-* [Deploy & serve ->](/versions/1.0.21/deploy-and-serve): Deploy your agents locally, as serverless in the cloud or on your K8s cluster, with different protocols and tool sandboxes
+* [Quickstart ->](/agentscope/1.0.21/quickstart): Build your first chatbot agent in 5 minutes
+* [Out-of-box agents ->](/agentscope/1.0.21/out-of-box-agents): Try out our collection of pre-built agents for various use cases
+* [Basic concepts & building blocks ->](/agentscope/1.0.21/basic-concepts): Learn about the core abstractions in AgentScope and how to use them
+* [Observe & evaluate ->](/agentscope/1.0.21/observe-and-evaluate): Learn how to observe and evaluate your agents with built-in OTel support and evaluation tools
+* [Deploy & serve ->](/agentscope/1.0.21/deploy-and-serve): Deploy your agents locally, as serverless in the cloud or on your K8s cluster, with different protocols and tool sandboxes
 
 ---
 

versions/1.0.21/en/observe-and-evaluate/observability.mdx → agentscope/1.0.21/en/observe-and-evaluate/observability.mdx

@@ -206,7 +206,7 @@ def my_sync_fn(x: int) -> int:
 
 Token usage is tracked by the model layer and is included in trace metadata where supported. When you connect to **AgentScope Studio**, token consumption is visualized in the Studio UI so you can monitor cost and usage per run. For third-party backends, token-related attributes are exported with the LLM spans according to the OpenTelemetry semantic conventions used by AgentScope.
 
-For programmatic access to usage after a model call, use the `usage` field on the [ChatResponse](/versions/1.0.21/en/building-blocks/models) returned by the model.
+For programmatic access to usage after a model call, use the `usage` field on the [ChatResponse](/agentscope/1.0.21/en/building-blocks/models) returned by the model.
 
 ---
 
@@ -217,4 +217,4 @@ For programmatic access to usage after a model call, use the `usage` field on th
 - Use **tracing_url** to send traces to Arize-Phoenix, Langfuse, Alibaba Cloud CloudMonitor, or any OTLP endpoint.
 - Use **@trace_llm**, **@trace_reply**, **@trace_format**, **@trace_toolkit**, **@trace_embedding**, and **@trace** when implementing custom models, agents, or formatters so they appear in the same trace tree.
 
-For evaluation of agent behavior and benchmarks, see [Evaluation](/versions/1.0.21/en/observe-and-evaluate/evaluation).
+For evaluation of agent behavior and benchmarks, see [Evaluation](/agentscope/1.0.21/en/observe-and-evaluate/evaluation).

versions/1.0.21/en/others/faq.mdx → agentscope/1.0.21/en/others/faq.mdx

@@ -52,7 +52,7 @@ Create a custom model class by inheriting from `agentscope.model.ChatModelBase`
 </Accordion>
 
 <Accordion title="How do I monitor token usage in AgentScope?">
-AgentScope Studio provides visualization of token usage and tracing. See the [Observability](/versions/1.0.21/en/observe-and-evaluate/observability) section for details.
+AgentScope Studio provides visualization of token usage and tracing. See the [Observability](/agentscope/1.0.21/en/observe-and-evaluate/observability) section for details.
 </Accordion>
 
 <Accordion title="Why do I need different Formatters for different LLMs?">
@@ -77,7 +77,7 @@ The two are **complementary**—you can even fine-tune a model to better leverag
 <AccordionGroup>
 
 <Accordion title="How do I create my own agent?">
-You can use the `ReActAgent` class directly, or create a custom agent by inheriting from `AgentBase` or `ReActAgentBase`. See the [Agent](/versions/1.0.21/en/basic-concepts/agent) section for details.
+You can use the `ReActAgent` class directly, or create a custom agent by inheriting from `AgentBase` or `ReActAgentBase`. See the [Agent](/agentscope/1.0.21/en/basic-concepts/agent) section for details.
 </Accordion>
 
 <Accordion title="What's the difference between agent_base, react_agent_base, and react_agent?">
@@ -87,23 +87,23 @@ You can use the `ReActAgent` class directly, or create a custom agent by inherit
 </Accordion>
 
 <Accordion title="Does AgentScope support dynamic Pydantic models for structured output?">
-Yes. AgentScope supports **dynamic JSON Schema generation** and leverages Pydantic for validation in ReAct agents. See the [Agent](/versions/1.0.21/en/basic-concepts/agent) page for details.
+Yes. AgentScope supports **dynamic JSON Schema generation** and leverages Pydantic for validation in ReAct agents. See the [Agent](/agentscope/1.0.21/en/basic-concepts/agent) page for details.
 </Accordion>
 
 <Accordion title="Can I use Anthropic-style skills in AgentScope?">
 Yes. Place your skill definitions in a directory following AgentScope's [skill structure](https://github.com/agentscope-ai/agentscope/blob/main/examples/functionality/agent_skill/README.md), then register them via `toolkit.register_agent_skill()`.
 </Accordion>
 
 <Accordion title="How do I forward the streaming output of agents to my own frontend?">
-Use the pre-hook of the `print` function to forward printed messages. See the [Hooking Functions](/versions/1.0.21/en/building-blocks/hooking-functions) section for details.
+Use the pre-hook of the `print` function to forward printed messages. See the [Hooking Functions](/agentscope/1.0.21/en/building-blocks/hooking-functions) section for details.
 </Accordion>
 
 <Accordion title="What built-in tools does AgentScope provide?">
 AgentScope includes a set of built-in tools such as `execute_python_code`, `execute_shell_command`, and `write_text_file`. You can find the full list under the `agentscope.tool` module.
 </Accordion>
 
 <Accordion title="Is MCP (Model Control Protocol) supported?">
-Yes. AgentScope supports standard-compliant MCP for tool and service integration. See the [Tool Capabilities](/versions/1.0.21/en/building-blocks/tool-capabilities) page for details.
+Yes. AgentScope supports standard-compliant MCP for tool and service integration. See the [Tool Capabilities](/agentscope/1.0.21/en/building-blocks/tool-capabilities) page for details.
 </Accordion>
 
 </AccordionGroup>

versions/1.0.21/en/out-of-box-agents/data-science.mdx → agentscope/1.0.21/en/out-of-box-agents/data-science.mdx

@@ -92,7 +92,7 @@ The Data Science Agent supports multiple data source formats:
 All uploaded files are automatically copied to the `/workspace` directory in the sandbox for secure processing.
 
 <Note>
-The Data Science Agent is built with DashScope chat models. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/versions/1.0.21/en/building-blocks/models#provider-reference).
+The Data Science Agent is built with DashScope chat models. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/agentscope/1.0.21/en/building-blocks/models#provider-reference).
 </Note>
 
 </Step>

versions/1.0.21/en/out-of-box-agents/deep-research.mdx → agentscope/1.0.21/en/out-of-box-agents/deep-research.mdx

@@ -118,7 +118,7 @@ while True:
 ```
 
 <Note>
-The example is built with DashScope chat model. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/versions/1.0.21/en/building-blocks/models#provider-reference).
+The example is built with DashScope chat model. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/agentscope/1.0.21/en/building-blocks/models#provider-reference).
 </Note>
 
 </Step>

versions/1.0.21/en/tune-agent/model-selection-tuning.mdx → agentscope/1.0.21/en/tune-agent/model-selection-tuning.mdx

@@ -81,7 +81,7 @@ The workflow function executes your agent logic with a given model and returns a
 - Run inference using that model
 - Return a `WorkflowOutput` object containing the model's response
 
-This pattern is identical to the one introduced in [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent#workflow-function). For a complete implementation example — including how to set up an agent, format messages, and return structured output — please refer to that guide.
+This pattern is identical to the one introduced in [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent#workflow-function). For a complete implementation example — including how to set up an agent, format messages, and return structured output — please refer to that guide.
 
 <Note>
 Your function must return `WorkflowOutput`. Do not define custom output classes.
@@ -95,7 +95,7 @@ The judge function evaluates the output of the workflow and assigns a numerical
 - Compute a scalar `reward` (e.g., accuracy, BLEU score, or inverse latency)
 - Return a `JudgeOutput` object with `reward` and `metrics`
 
-This follows the same contract described in [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent#judge-function). That guide provides a step-by-step example of building a correctness-based judge.
+This follows the same contract described in [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent#judge-function). That guide provides a step-by-step example of building a correctness-based judge.
 
 ## Using Built-in Judges
 

versions/1.0.21/en/tune-agent/model-weights-tuning.mdx → agentscope/1.0.21/en/tune-agent/model-weights-tuning.mdx

@@ -35,7 +35,7 @@ ray start --head
 
 ## Refine Workflow Function
 
-Continuing from [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent.mdx), assume you have a task dataset and judge function ready. Now, refine your workflow function for model weights tuning:
+Continuing from [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent.mdx), assume you have a task dataset and judge function ready. Now, refine your workflow function for model weights tuning:
 
 ```python
 async def example_workflow_function(