memorax-code AGENTS.md

MemoraX Code Agent Guide

This file defines the durable working rules for coding agents in this repository. Current user instructions, live source, and executable tests take precedence over generated memory or historical context.

1. Start Safely

• Run git status --short --branch before editing. Confirm the intended worktree and preserve unrelated tracked, untracked, and staged changes.
• Read the nearest implementation and tests before changing behavior. Prefer a small, layered change with an explicit verification target.
• Do not mix unrelated formatting, renaming, dependency updates, or lockfile rewrites into the task. Do not run broad auto-fix commands unless required.
• Use English for source identifiers, comments, docstrings, and canonical public documentation. Keep README.md and README.zh.md synchronized for user-facing changes.
• Treat .repo_memory/ as local retrieval guidance, not current-code authority. It is Git-ignored and must not leak into public artifacts.
• Use isolated MEMORAX_CODE_HOME, CODEX_HOME, CLAUDE_CONFIG_DIR, and OPENCODE_CONFIG_DIR locations for lifecycle, install, migration, or destructive tests.

2. Architecture Routing

ARCHITECTURE.md is the canonical map for system shape, package ownership, runtime flows, Backend source and test placement, dependency direction, stable root surfaces, and executable architecture contracts.

Read it before adding or moving modules or tests, changing entrypoints, control/data flow, state or authority, packaging/materialization, or cross-package or cross-capability dependencies.

Preserve the documented boundaries. When an intentional architecture change is required, update ARCHITECTURE.md and the affected executable contract in the same change, then run the matching verification profile in Section 5.

3. Hook, Session, and Scope Invariants

• Hook commands are versioned and client-qualified. Required session, turn, or prompt correlation must be validated at the HTTP boundary; incomplete, conflicting, unknown, or client-inapplicable identities fail closed.
• Codex rollout JSONL, Claude Code and CodeBuddy/WorkBuddy transcript JSONL, DSH's exact persisted Session Event Log interval, matching OpenCode SDK session-message records, and Trae's validated UserPromptSubmit/Stop Hook pair are the content authorities for their respective automatic writeback. Hook or plugin text is not a fallback outside Trae's narrow primary-authority exception; local trace, latest-turn guesses, and another client's format are never fallbacks.
• Session, turn metadata, trace, and operational identity always include the client. Equal native IDs from different clients must remain isolated.
• A live session is pinned to its resolved workspace and repository scope. Linked worktrees of one repository may share repository scope; unrelated repositories and genuine non-Git workspaces keep separate local identity. The documented direct-.git exception may use local-folder scope when its internal metadata is malformed or incomplete, then upgrade in-session only to verified Git scope for the same Base User ID and canonical workspace root. Discard pending fallback writeback during that upgrade. Missing, unreadable, malformed, or conflicting scope authority outside this narrow exception must not silently fall back or rebind.
• Repository resolution is read-only and must not execute Git merely to derive memory identity. Preserve path canonicalization, Git marker validation, symlink/junction containment, and fail-closed behavior.
• Consume turn metadata only after the matching downstream operation is accepted. Rejection, missing content, interruption, or concurrent replacement must retain or discard metadata with an explicit reason.
• Backend connection, token, PID, Hook generation, and lifecycle authority use versioned private records. Cross-process read/modify/write requires bounded locking or equivalent version validation; in-memory serialization is not sufficient.
• Keep the default Backend on loopback. External binding requires explicit opt-in and authentication.