> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # Memory Qoder CLI rebuilds context for every session. Knowledge that should carry across sessions comes from two memory systems: * Static memory: durable instructions maintained by you or your team. It includes `AGENTS.md` files and rules, useful for coding standards, project structure, commands, and collaboration rules. * Auto-memory: local Markdown memories saved by Qoder CLI when the feature is enabled, useful for preferences, feedback, project background, and references that should be available later. Memory is context, not an enforcement layer. To block commands, tools, or paths regardless of model behavior, use permissions or Hooks. ## Memory Types | Mechanism | Written by | Best for | Scope | View with | | ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- | | Static memory | You or your team | Explicit, stable instructions to apply every session; use `AGENTS.md` for broad guidance and rules for topic- or file-scoped instructions | User, project, local project, plugin-provided | `/memory` | | Auto-memory | Qoder CLI | Reusable learnings from conversation, such as preferences, feedback, project background, and references | Project; optional user scope | `/memory` opens the auto-memory folder; `/memory manage` manages topic files | ## Static Memory Static memory is written and maintained explicitly by you or your team. Use `AGENTS.md` for broad project guidance and stable conventions, and use rules to split related instructions into Markdown files by topic or file area. ### Static Memory Files `AGENTS.md` is the default context file name in Qoder CLI, and rules are Markdown rule files kept under `rules/` directories. When memory is loaded or refreshed, Qoder CLI reads available static memory files and injects matching content as session context. #### Common Locations ```text theme={null} ~/.qoder/AGENTS.md /AGENTS.md /AGENTS.local.md /.qoder/rules/*.md ``` | Location | Purpose | Commit it? | | ----------------------------- | --------------------------------------------------------------------------- | ---------- | | `~/.qoder/AGENTS.md` | Cross-project preferences and personal workflow habits for the current user | No | | `/AGENTS.md` | Team-shared project rules, architecture notes, and common commands | Yes | | `/AGENTS.local.md` | Machine-local project notes, such as local URLs or personal test data | No | | `/.qoder/rules/*.md` | Focused project rules split by topic or file area | Yes | Advanced setups can change the file name with `context.fileName`, which accepts a single string or an array of strings. The default is `AGENTS.md`. #### Loading Logic When memory is loaded or refreshed, Qoder CLI searches upward for project memory and checks the project rules directory at each level: * User memory: loads `AGENTS.md` from the user config directory. * Project and local project memory: in trusted workspaces, searches from the current workspace directory upward for `AGENTS.md`, `AGENTS.local.md`, and `.qoder/rules/**/*.md`, stopping by default at the directory containing `.git`. * Rule frontmatter decides how rules load: always-on rules load with the surrounding project memory; file-scoped rules load on demand only after Qoder CLI accesses a matching file; manual and model-decision rules do not inject their body at startup. * Subdirectory memory: not preloaded at startup. Only after Qoder CLI successfully reads a file inside a subdirectory does it walk upward from that file's directory and load any not-yet-loaded `AGENTS.md`, `AGENTS.local.md`, or matching `.qoder/rules/**/*.md`. That on-demand content enters later context and appears in `/memory`. For example, starting in `/repo/packages/app` checks: ```text theme={null} /repo/packages/app/AGENTS.md /repo/packages/app/.qoder/rules/*.md /repo/packages/AGENTS.md /repo/packages/.qoder/rules/*.md /repo/AGENTS.md /repo/.qoder/rules/*.md ``` Starting in `/repo` does not preload `/repo/packages/app/AGENTS.md` or `/repo/packages/app/.qoder/rules/*.md`; they are loaded on demand only after Qoder CLI accesses a file under `packages/app`. ### Rules Rules are focused instructions kept as separate Markdown files under a `rules/` directory, instead of one large `AGENTS.md`. Split them by topic (testing, API, security) or by the part of the codebase they govern. Each rule is a plain Markdown file; optional frontmatter controls when it applies. Qoder CLI rule frontmatter is compatible with rule settings configured in Qoder Desktop. Rules synced or copied from Qoder Desktop can keep their existing trigger settings. #### Where Rules Live Rules come from two scopes: | Scope | Location | Applies to | Commit it? | | ------- | -------------------------------- | ------------------------------------------------------ | ---------- | | Project | `/.qoder/rules/**/*.md` | The project where the file lives, shared with the team | Yes | | User | `~/.qoder/rules/**/*.md` | Every project you open, personal to your machine | No | Project rules can sit at any level of the workspace, including nested subdirectories, and are discovered by walking up from the working directory. User rules are read from your user config directory and apply across all projects. #### Supported Activation Modes Qoder CLI supports four rule activation modes. If no loading-related frontmatter is set, the rule is always-on by default. When `trigger` is present, it takes precedence over `alwaysApply`. | Activation mode | Best for | Configuration | Loading behavior | | --------------- | ------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Always-on | General rules that should apply in every session | No loading frontmatter, `trigger: always_on`, or `alwaysApply: true` | Loads the rule body when memory is loaded or refreshed. | | Manual | Rules that should only be used when explicitly introduced | `trigger: manual` or `alwaysApply: false` | Does not automatically inject the rule body. | | Model decision | Rules that can be selected from a short relevance description | `trigger: model_decision` + a non-empty `description` | Injects only the rule path and description; the model reads the rule body when relevant. | | File-scoped | Rules that apply only to certain files or directories | `trigger: glob` + `glob`, or `paths` | Loads the rule body on demand after Qoder CLI accesses a matching file. | `trigger: model_decision` requires a non-empty `description`, and `trigger: glob` requires a valid `glob`. If the required field is missing, the rule body is not injected automatically. #### Configuration Examples Always-on rules can omit frontmatter or set the mode explicitly: ```markdown theme={null} --- trigger: always_on --- # General Project Conventions - Run tests before submitting changes. - Update documentation when public APIs change. ``` Manual rules are not injected into context automatically: ```markdown theme={null} --- trigger: manual --- # Release Checklist - Confirm the version number is updated. - Confirm the changelog is complete. ``` Model-decision rules need a `description` so the model can decide whether to read the rule body: ```markdown theme={null} --- trigger: model_decision description: Use when changing API handlers, schemas, or error envelopes. --- # API Rules - Validate request bodies with the shared schemas in `src/api/schema/`. - Every handler must return the standard error envelope. ``` For file-scoped rules, use `trigger: glob` + `glob`: ```markdown theme={null} --- trigger: glob glob: - src/api/** - "**/*.test.ts" --- # API Rules - Validate request bodies with the shared schemas in `src/api/schema/`. - Every handler must return the standard error envelope. ``` You can also use `paths` directly for path-scoped rules: ```markdown theme={null} --- paths: - src/api/** - "**/*.test.ts" --- ``` #### Frontmatter Options | Option | Values | Behavior | | ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `trigger` | `always_on`, `manual`, `model_decision`, `glob` | Activation mode. `always_on` is always-on; `manual` is manual; `model_decision` lets the model decide and requires a non-empty `description`; `glob` is file-scoped and requires a valid `glob`. | | `description` | String | Description for model-decision rules, used to decide whether to read the rule body. | | `glob` | One glob or a list of globs | Used with `trigger: glob` to define the file range where the rule applies. | | `paths` | One glob or a list of globs | Defines the file range where the rule applies, equivalent to `trigger: glob` + `glob`. | Notes on `glob` and `paths`: * They are lists of glob patterns. Project-rule globs match relative to the directory that contains the `.qoder/` folder; user-rule globs match relative to the current project root. * They are internal routing metadata: they decide when the rule applies and are not injected into the model context with the rule body. Patterns use gitignore-style matching. Common examples: | Pattern | Matches | | ---------------------- | --------------------------------------------------- | | `**/*.ts` | All TypeScript files in any directory | | `src/**/*` | All files under `src/`, at any depth | | `*.md` | Markdown files in any directory | | `/*.md` | Markdown files in the project root only | | `src/components/*.tsx` | Files directly under `src/components/` (not nested) | #### Updating Rules Mid-Session After a rule loads, Qoder CLI keeps watching the file for the rest of the session. Editing a loaded rule — regardless of how it was loaded, project or user scope — is detected on the next turn, so you can refine a rule and have Qoder CLI follow the updated version without restarting. A path-scoped rule is also picked up the first time it matches an accessed file. ### Writing Good Instructions Use `AGENTS.md` for facts and conventions that should still matter next session. Good entries include: * Build, test, format, and release commands * Project layout and important module boundaries * Code style, naming, and review requirements * Team workflows for commits, branches, or test data * Repository-specific security or compliance notes Avoid storing: * Temporary state for the current task * Fast-changing schedule or progress notes * Long duplicated content that can already be read from code or README files * Policies that must be enforced. Use permissions or Hooks for enforcement Specific, verifiable instructions work best: ```markdown theme={null} # Development - Use `pnpm test` before committing changes. - API handlers live in `src/api/handlers/`. - Do not modify generated files under `src/generated/`. ``` ### Import Other Files `AGENTS.md` can import another file with `@path/to/file`. Relative paths resolve from the file containing the import. ```markdown theme={null} # Project Notes See @README.md for the high-level architecture. Use @docs/testing.md for test data setup. ``` Import behavior: * Relative paths, absolute paths, and `~/` paths are supported. * `@...` inside Markdown inline code or fenced code blocks is ignored. * Project and local project memory files can import files inside the project boundary by default. Imports outside that boundary require explicit approval or a security setting. * Imports are expanded recursively with a depth limit to avoid infinite cycles. To mention `@README.md` literally, wrap it in backticks: `` `@README.md` ``. ## Auto-Memory When auto-memory is enabled, Qoder CLI saves useful cross-session information as local Markdown files while you work. It does not save every conversation turn; it decides whether a detail is useful enough for future sessions. ### What Auto-Memory Stores Auto-memory uses four content types: | Type | Use | | ----------- | ------------------------------------------------------------------------------------- | | `user` | User role, long-term preferences, and cross-project habits | | `feedback` | Corrections or confirmations about how Qoder CLI should work with you | | `project` | Project background, constraints, or decision reasons not directly derivable from code | | `reference` | Locations of external systems, boards, dashboards, or documents | Auto-memory files are local to the machine. They do not become shared with other machines just because you commit code. They can also become stale; when a memory mentions a file, function, setting, or external state, Qoder CLI should verify the current fact before acting on it. ### Enable Auto-Memory Auto-memory runs only in interactive sessions. In the current implementation, the effective switch is an environment variable: ```bash theme={null} QODER_MEMORY=1 qodercli ``` To also enable the cross-project user-scope auto-memory root: ```bash theme={null} QODER_MEMORY=1 QODER_MEMORY_USER=1 qodercli ``` `QODER_MEMORY_USER` only takes effect when `QODER_MEMORY` is enabled. When auto-memory is not enabled, `/memory` can still manage `AGENTS.md` files; `/memory manage` shows that auto-memory is unavailable. ### Auto-Memory Storage Project-scope auto-memory is stored under the Qoder project config directory: ```text theme={null} ~/.qoder/projects//memory/ ``` When user-scope auto-memory is enabled, Qoder CLI also uses: ```text theme={null} ~/.qoder/memory/ ``` Each auto-memory directory contains a `MEMORY.md` index and optional topic files: ```text theme={null} memory/ ├── MEMORY.md ├── user-preferences.md ├── feedback-testing.md └── project-release-context.md ``` `MEMORY.md` is an index, not the place for long-form memory content. At startup, Qoder CLI loads each active auto-memory root's `MEMORY.md`, up to the first 200 lines or about 25KB. Detailed notes should live in topic files referenced by the index. ## View and Manage In TUI, run: ```text theme={null} /memory ``` `/memory` opens the memory overview. It shows user, project, and local project memory files, and shows `Open auto-memory folder` entries when auto-memory is enabled. Selecting one opens the corresponding auto-memory folder with the system file manager. To manage auto-memory topic files inside the TUI: ```text theme={null} /memory manage ``` `/memory manage` opens the auto-memory manager. It lets you view, open, edit, or delete auto-memory topic files. When a topic file is deleted, Qoder CLI also removes the corresponding `MEMORY.md` index entry. ### Remember or Forget Use natural language: ```text theme={null} Remember that this project's integration tests require local Redis first. ``` Or: ```text theme={null} Forget the old deployment-script memory. ``` If the information is really a team rule or project instruction, ask Qoder CLI to write it to `AGENTS.md` instead: ```text theme={null} Add this testing rule to the project AGENTS.md. ``` ## Troubleshooting ### Qoder CLI Is Not Following `AGENTS.md` * Run `/memory` and confirm the target file appears. * Confirm the current directory is trusted; untrusted folders do not apply project settings, Hooks, MCP, or `AGENTS.md` files. * Look for conflicting instructions between user, project, and local project files. * Check whether `agentsMdExcludes` excludes the file. * Make vague instructions more specific and verifiable. ### `@` Imports Do Not Load * Confirm the path exists and is not inside Markdown inline code or a fenced code block. * Imports outside the project boundary are blocked by default; approve the external import or adjust the security setting. * npm package names, mentions, and plain `@word` text are not treated as file imports. ### Auto-Memory Does Not Appear * Confirm you are in a TUI interactive session. * Confirm the session was started with `QODER_MEMORY=1`. * Run `/memory` and check whether the auto-memory folder entry appears, or run `/memory manage` to check whether the auto-memory manager is available. * Auto-memory does not save something every turn. Creating zero memories is normal when no reusable information was found. ### Memory Is Stale Memory reflects what was true when it was written. For current code, configuration, or external systems, trust the current files and systems first. If a memory is stale, update or delete it.