ReMe: Instructions file for Codex

AGENTS.md

This file guides coding agents working in the ReMe repository. Keep changes small, testable, and consistent with the contracts expressed by the current code.

Project Principles

ReMe is a local-first, file-native memory system for agents.

• User-owned workspace files are the durable source of truth.
• Indexes, catalogs, graphs, caches, and generated metadata must remain rebuildable.
• Prefer transparent formats and predictable behavior over hidden state.
• Preserve user control over workspace paths, configuration, and service boundaries.
• Keep concepts focused on project intent; let code and schemas describe implementation.

When convenience conflicts with these principles, favor data ownership, recoverability, and explicit behavior.

Sources of Truth

Use this order when documentation and implementation disagree:

1. Current code and public Pydantic schemas.
2. Tests that describe supported behavior.
3. CLI behavior and the built-in configuration.
4. README files and other development documentation.

Do not duplicate large implementation descriptions in documentation. Express the stable contract and link to the relevant module where useful. When behavior changes intentionally, update the implementation, schemas, tests, defaults, and concise documentation together.

Repository Map

• reme/reme.py: CLI entry point; dispatches start, find_reme, and client calls.
• reme/application.py: application assembly, dependency ordering, job execution, and lifecycle.
• reme/config/config_parser.py: YAML/JSON loading, environment expansion, dot-notation parsing, and deep config merging.
• reme/config/default.yaml: default service, jobs, steps, and components. Other files in reme/config/ are named configuration variants.
• reme/schema/application_config.py: typed application, component, and job configuration.
• reme/schema/: request, response, streaming, memory, graph, and file contracts.
• reme/components/application_context.py: application-wide wiring and in-memory shared state.
• reme/components/runtime_context.py: request-scoped data, response, streaming queue, and stop event.
• reme/components/base_component.py: component lifecycle, dependency binding, and workspace helpers.
• reme/components/component_registry.py: the frozen built-in registry template and application-local registry factory.
• reme/components/job/: base, stream, background, and cron job implementations.
• reme/components/service/: local CLI, HTTP, and MCP service backends.
• reme/components/: agent wrappers, model adapters, stores, catalogs, graphs, indexes, clients, tokenizers, and outbound proxies.
• reme/steps/: registered job steps grouped by common, file I/O, index, evolve, cookbook, and transfer concerns.
• reme/utils/: shared utilities, including service discovery, logging, web-static resolution, session I/O, token accounting, and wikilink handling.
• tests/unit/: primary fast, isolated validation suite.
• tests/integration/: service/model tests that may need credentials or external processes.
• reme_studio/: ReMe Studio frontend source plus the independently published reme_studio Python package and @agentscope-ai/reme_studio npm static distribution.
• plugins/: installable ReMe extensions, including Auto Fin and LME/BEAM plugins.
• integrations/: adapters that connect ReMe to external agent hosts, including the independent, self-contained DSH and OpenClaw TypeScript plugins plus the Claude Code and Hermes Agent integrations.
• skills/: standalone skills; reme_memory calls ReMe, while other skills may use separate tools or direct-file conventions.
• benchmark/ and cookbook/: runnable evaluations and example workflows.
• docs/: README-linked supporting pages and figures.
• github-pages/: VitePress build shell, generated-content assembly, documentation checks, and GitHub Pages output. The canonical theme and guides remain under docs/; .generated/ and dist/ are disposable.