> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to development documentation. Use it only with the matching development source. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# Reference

> Stable workspace, configuration, CLI, HTTP, and MCP contracts for ReMe.

This page records stable user-facing semantics and points to authoritative interfaces for the installed version. Exact parameters belong to runtime schemas and source code.

## Workspace

The default workspace is `.reme/` under the launch directory. Override it at startup:

```bash theme={null}
reme start workspace_dir=/path/to/workspace
```

The workspace uses the following top-level directories:

| Directory      | Meaning                                                                      | User editing                      |
| -------------- | ---------------------------------------------------------------------------- | --------------------------------- |
| `session/`     | Source conversations used by memory workflows                                | Usually read-only                 |
| `mem_session/` | Generated agent-wrapper sessions and configuration                           | Do not treat as user memory       |
| `resource/`    | Imported source material                                                     | Add, replace, or delete as needed |
| `daily/`       | Topic-named cards and date indexes produced from conversations and resources | Inspect and correct               |
| `digest/`      | Durable personal facts, procedures, and knowledge                            | Primary manual editing surface    |
| `metadata/`    | Derived indexes, graph, and catalogs                                         | Do not edit manually              |

<Note>
  `metadata/` can be rebuilt and must not be the only copy of memory. Backups should retain at least `session/`, `resource/`, `daily/`, and `digest/`. `mem_session/` contains generated runtime state rather than durable user memory.
</Note>

## Markdown Memory

Memory files are ordinary Markdown with optional YAML frontmatter:

```markdown theme={null}
---
name: Build checks
description: Checks required before submitting code
---

# Build checks

Run pytest before submitting. This rule was recorded in [[daily/2026-07-13/build-checks.md]].
```

* Paths are workspace-relative and file actions cannot escape the workspace.
* ReMe can add a missing `.md` suffix where appropriate.
* `[[path/to/file.md]]` is a workspace wikilink.
* Wikilinks use literal workspace-relative paths; ReMe does not infer `.md`, search by filename, or resolve folder notes.
* `name` and `description` are common summary fields. Treat other metadata as stable only when covered by the current schema.
* Prefer ReMe `move` / `delete` actions for linked files so related links can be checked.

## Configuration

Without `config=`, ReMe loads the built-in `default` configuration. A file passed through `config=` replaces that default and must contain a complete application configuration. Dot-notation arguments are then merged on top of whichever configuration was selected:

```bash theme={null}
# Use the built-in default with a small override
reme start service.port=8181

# Use a complete custom configuration, then override its port
reme start config=/path/to/config.yaml service.port=8181
```

Common top-level groups include:

| Setting                         | Meaning                                            |
| ------------------------------- | -------------------------------------------------- |
| `workspace_dir`                 | Workspace root                                     |
| `timezone`                      | Timezone for daily notes and scheduled jobs        |
| `service.backend`               | `http` or `mcp`                                    |
| `service.host` / `service.port` | Listen address                                     |
| `service.transport`             | MCP transport                                      |
| `jobs`                          | Background, scheduled, and served actions          |
| `components`                    | LLM, embedding, storage, and graph implementations |

Embedding retrieval is disabled by default. Enable both `components.as_embedding` and `components.embedding_store`, then set `components.file_store.default.embedding_store` to `default`. The configured vector dimension must match the selected model.

`${VAR}` and `${VAR:-default}` in string values expand from the environment. Never commit configuration or `.env` files containing secrets.

Authoritative sources:

* [`reme/config/default.yaml`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/default.yaml) for default jobs, components, and parameters;
* [`reme/schema/application_config.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/schema/application_config.py) for the top-level model;
* [`reme/config/config_parser.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/config_parser.py) for merge, override, and environment rules.

## CLI

The CLI has one uniform form:

```text theme={null}
reme <action> key=value nested.key=value
```

Common entrypoints:

```bash theme={null}
reme help          # actions served by the current service
reme version       # installed version
reme health_check  # component status
reme status        # component memory estimates and process RSS
reme find_reme     # locate a running ReMe process
reme reindex       # clear and rebuild the file index
reme traverse      # inspect a wikilink neighborhood
reme graph_snapshot # return the category-rooted digest graph
reme chat          # stream a read-only workspace-agent conversation; requires an LLM
```

`reme search` supports `start_date` and `end_date` as inclusive `YYYY-MM-DD` filters. The live watcher indexes Markdown in `daily/` and `digest/`; `reme reindex` additionally scans `resource/` and JSONL. Use `reme read` for Markdown. For a non-Markdown text result, inspect it with `reme stat` and then `reme load`, because `load` returns the complete file.

Auto Resource watches `md`, `txt`, `json`, `jsonl`, `csv`, `yaml`, and `html` files placed directly under `resource/` or in `resource/YYYY-MM-DD/`. Auto Memory preserves source messages under `session/dialog/` but omits recalled tool results and base64 data from the transcript. Generated daily filenames come from validated content names; provenance fields such as `session_id`, `source_conversation`, and `source_resource` remain the stable lookup identity.

Actions other than `start` connect to the running service. Runtime `reme help` and `reme/config/default.yaml` are the authoritative action and parameter lists.

## HTTP and MCP

The default HTTP service exposes served jobs as `POST /{action}`. While it is running, use:

* `/` for ReMe Studio when a web build is available;
* `/docs` for interactive OpenAPI documentation;
* `/openapi.json` for the machine-readable schema.

Start MCP with:

```bash theme={null}
reme start service.backend=mcp service.transport=streamable-http
```

The default MCP URL is `http://127.0.0.1:2333/mcp`. MCP clients discover the current tool list on connection. Stream jobs such as `chat` are not exposed as MCP tools.

## Compatibility and Changes

* Python and dependency ranges: [`pyproject.toml`](https://github.com/agentscope-ai/ReMe/blob/main/pyproject.toml)
* Request, response, and persistent structures: [`reme/schema/`](https://github.com/agentscope-ai/ReMe/tree/main/reme/schema)
* Behavioral boundaries: [`tests/`](https://github.com/agentscope-ai/ReMe/tree/main/tests)
* Version changes: [GitHub Releases](https://github.com/agentscope-ai/ReMe/releases)