| 1 | # Reasonix project memory |
| 2 | |
| 3 | This file is loaded into every session's system prompt (the cache-stable prefix), |
| 4 | so keep it concise and durable — it is the project's standing instructions to the |
| 5 | agent. It is the Reasonix analog of Claude Code's CLAUDE.md. |
| 6 | |
| 7 | ## Conventions |
| 8 | |
| 9 | - Go kernel under `internal/`; each package owns one concern and documents it in a |
| 10 | package comment. Match the surrounding comment density and idiom when editing. |
| 11 | - One transport-agnostic `control.Controller` sits behind every frontend (chat |
| 12 | TUI, HTTP/SSE serve, Wails desktop). Add behavior to the controller, not a |
| 13 | frontend, so all three inherit it. |
| 14 | - Cache-first: the system-prompt prefix (base prompt + tools + memory) must stay |
| 15 | byte-stable across turns so DeepSeek's automatic prefix cache stays warm. Never |
| 16 | mutate it mid-session — ride the turn tail instead (see `control.Compose`). |
| 17 | |
| 18 | ## Memory |
| 19 | |
| 20 | - Standing instructions are hierarchical: committed/shared `REASONIX.md`, |
| 21 | `AGENTS.md`, and `CLAUDE.md`; personal `*.local.md` variants; matching files in |
| 22 | ancestor directories; and user-global files under the memory state root |
| 23 | (`REASONIX_STATE_HOME`, otherwise `REASONIX_HOME`, otherwise `~/.reasonix` on |
| 24 | macOS/Linux or `%APPDATA%\reasonix` on Windows). All distinct supported files |
| 25 | in a directory load; `AGENTS.md` is not merely a fallback. |
| 26 | - `@path` on its own line imports another file's contents. |
| 27 | - `#<note>` in chat quick-adds an always-on instruction. The `remember` tool |
| 28 | instead saves a fallible background fact (frontmatter file + `MEMORY.md` |
| 29 | index). Fact `type` classifies content; independent `scope` controls whether it |
| 30 | is project-only (the default) or explicitly global. The index loads into the |
| 31 | stable prefix on the next session; global user/feedback bodies also load as |
| 32 | lower-priority compatibility guidance. The current turn receives a tail note. |
| 33 | |
| 34 | ## Notes |
| 35 | |
| 36 | ## Pre-push CI simulation |
| 37 | |
| 38 | Run these **before every commit** to catch the fastest CI failures locally: |
| 39 | |
| 40 | ```bash |
| 41 | gofmt -w . # catches gofmt (saves ~13s CI) |
| 42 | go vet ./... # catches vet warnings (saves ~52s CI/lint) |
| 43 | go test ./internal/tool/builtin/ ./internal/boot/ # catches tool/boot test breaks |
| 44 | ``` |
| 45 | |
| 46 | CI runs `golangci-lint` (not locally available), but gofmt + vet already block ~80% of fast-fail scenarios. |
| 47 | |
| 48 | ## Import cycle rule |
| 49 | |
| 50 | Before importing a new internal package from a non-test file, verify the target package's **test files** aren't already importing back to you: |
| 51 | |
| 52 | ``` |
| 53 | # BAD: agent(_test.go) → tool/builtin(sessions.go) → agent → setup failed |
| 54 | ``` |
| 55 | |
| 56 | Use `go test ./path/to/target/` to detect cycles **before** pushing. A `[setup failed]` message means a cycle exists. |
| 57 | |
| 58 | ## PR hygiene |
| 59 | |
| 60 | - **One force-push per round of review feedback.** Multiple force-pushes destroy review history and confuse reviewers. |
| 61 | - **Keep the PR diff minimal.** Only the files relevant to the PR's purpose — no stray changes from other branches. |
| 62 | - **Amend, don't add commits, for review feedback** — keeps the commit history clean. |
| 63 | |
| 64 | ## Cache-impact PR metadata |
| 65 | |
| 66 | When PR changes touch files under `internal/boot/`, `internal/tool/`, `internal/provider/`, or other cache-sensitive paths (listed in `scripts/check-cache-impact.sh`), the PR body MUST include these lines at the end: |
| 67 | |
| 68 | ``` |
| 69 | Cache-impact: <none|low|medium|high> — <reason> |
| 70 | Cache-guard: <focused guard test/command or existing guard rationale> |
| 71 | ``` |
| 72 | |
| 73 | If the PR also touches files under `internal/config/`, `internal/memory/`, `internal/outputstyle/`, `internal/skill/`, or `internal/boot/`, add: |
| 74 | |
| 75 | ``` |
| 76 | System-prompt-review: <reviewer/approval note> |
| 77 | ``` |
| 78 | |
| 79 | Values `n/a`, `none`, `todo`, `tbd` are rejected — use a descriptive reason instead. |
| 80 |