> ## 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 > Static memory (AGENTS.md) and Auto-Memory mechanisms in Qoder CLI, including file locations and management Qoder CLI reconstructs the context for every session. Knowledge that needs to be retained across sessions primarily comes from two types of memory: * Static memory: Persistent instructions maintained by you or your team, including `AGENTS.md` and rules. It is suitable for development standards, project structure, common commands, and collaboration conventions. * Auto-Memory: Markdown memory saved locally by Qoder CLI when enabled. It is suitable for recording preferences, feedback, project background, and external references that remain useful in subsequent sessions. Memory is provided to the model as context, but it is not a strict enforcement policy. When you need to strictly block certain commands, tools, or paths, use permission configuration or Hooks. ## Memory Types | Mechanism | Author | Suitable Content | Scope | Access Point | | ------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Static memory | User or team | Clear, stable instructions expected to be followed in every session; `AGENTS.md` for overall instructions, rules split by topic or file scope | User-Level, project-level, local project level, provided by plugins | `/memory` | | Auto-Memory | Qoder CLI | Reusable information learned from conversations, such as preferences, feedback, project background, and external resource locations | project-level; optionally User-Level | `/memory` to open the auto-memory folder; `/memory manage` to manage topic files | ## Static Memory Static memory is explicitly written and maintained by you or your team. `AGENTS.md` is suitable for hosting overall project instructions and stable conventions, while rules are ideal for splitting similar instructions into multiple Markdown files by topic or file scope. ### Static Memory Files `AGENTS.md` is the default context file name for Qoder CLI, and rules are Markdown Rule Files placed in the `rules/` directory. When starting or refreshing memory, Qoder CLI reads the available static memory files and injects the matching content into the session as context. #### Common Locations ```text theme={null} ~/.qoder/AGENTS.md /AGENTS.md /AGENTS.local.md /.qoder/rules/**/*.md ``` | Location | Purpose | Suitable to Commit | | -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------ | | `~/.qoder/AGENTS.md` | Cross-project general preferences and working habits for the current user | No | | `/AGENTS.md` | Team-shared project rules, architecture instructions, and common commands | Yes | | `/AGENTS.local.md` | Project-private instructions on the current machine, such as local service addresses or personal test data | No | | `/.qoder/rules/**/*.md` | Project rules split by topic or file scope | Yes | If you need to use other file names, you can set a single file name or an array of file names via `context.fileName`. The default value is `AGENTS.md`. #### Loading Logic When starting or refreshing memory, Qoder CLI searches upwards for project memory and checks the project rules directory at each level: * User-Level Memory: Loads `AGENTS.md` from the User Configuration Directory. * Project and local project level memory: Within a Trusted Workspace, searches upwards from the current Workspace directory for `AGENTS.md`, `AGENTS.local.md`, and `.qoder/rules/**/*.md`, stopping by default at the directory containing `.git`. * The frontmatter of rules determines the loading behavior: rules that always take effect are loaded along with the project memory; rules that apply to specific files are loaded on demand only after Qoder CLI accesses a matching file; manual rules and model-decision rules do not have their body injected at startup. * Subdirectory memory: Not preloaded at startup. Only after Qoder CLI successfully reads a file in a subdirectory will it search upwards from that file's directory to supplement any previously unloaded `AGENTS.md`, `AGENTS.local.md`, or matching `.qoder/rules/**/*.md`. This on-demand loaded content enters the subsequent context and is displayed in `/memory`. For example, when starting in `/repo/packages/app`, it 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 ``` If started from `/repo`, `/repo/packages/app/AGENTS.md` or `/repo/packages/app/.qoder/rules/*.md` will not be preloaded; they are loaded on demand only after accessing files under `packages/app`. ### Rules Rules are instruction files placed in the `rules/` directory and split by topic, used to replace a single bloated `AGENTS.md`. They can be split by topic (testing, API, security) or by the code areas they govern. Each rule is a standard Markdown file; the optional frontmatter determines when it takes effect. The rules frontmatter in Qoder CLI is compatible with the rules settings configured in Qoder Desktop; rule files synced or copied from Qoder Desktop can continue to use their original trigger configurations. #### Storage Locations Rules have two scopes: | Scope | Location | Effective Range | Suitable to Commit | | ------------- | -------------------------------- | ----------------------------------------------------------- | ------------------ | | project-level | `/.qoder/rules/**/*.md` | The project where the file is located, shared with the team | Yes | | User-Level | `~/.qoder/rules/**/*.md` | Every project you open, for local personal use only | No | project-level rules can be located at any level of the Workspace (including nested subdirectories) and are discovered by searching upwards from the working directory. User-Level rules are read from the User Configuration Directory and apply to all projects. #### Supported Activation Methods Qoder CLI supports four activation methods for rules. When no loading-related frontmatter is configured, rules are always active by default; `trigger` takes precedence over `alwaysApply` when present. | Activation Method | Suitable Scenario | Configuration Method | Loading Behavior | | ----------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Always active | General rules to be followed in every session | Omit loading frontmatter, or set `trigger: always_on`, or set `alwaysApply: true` | Loads the rule body when starting or refreshing memory. | | Manual inclusion | Occasionally used rules that require explicit inclusion | `trigger: manual` or `alwaysApply: false` | Does not automatically inject the rule body. | | Model decision | Rules where a single description can determine relevance to the current task | `trigger: model_decision` + non-empty `description` | Injects only the rule path and description; the model reads the rule body if it determines relevance. | | Specific files | Rules that apply only to certain files or directories | `trigger: glob` + `glob`, or directly configure `paths` | Loads the rule body on demand after Qoder CLI accesses a matching file. | `trigger: model_decision` must be set with a non-empty `description`; `trigger: glob` must be set with a valid `glob`. If required fields are missing, the rule body will not be automatically injected into the context. #### Configuration Examples Rules that are always active can omit the frontmatter or be explicitly configured: ```markdown theme={null} --- trigger: always_on --- # General Project Conventions - Run tests before committing. - Update documentation when modifying public APIs. ``` Rules for manual inclusion are not automatically injected into the context: ```markdown theme={null} --- trigger: manual --- # Release Checklist - Confirm the version number has been updated. - Confirm the changelog has been updated. ``` Model decision rules require a `description` to determine whether to read the rule body: ```markdown theme={null} --- trigger: model_decision description: Use when modifying API handlers, schemas, or API error structures. --- # API Rules - Use shared schemas under `src/api/schema/` to validate request bodies. - Each handler must return a standard error structure. ``` When applying to specific files, you can use `trigger: glob` + `glob`: ```markdown theme={null} --- trigger: glob glob: - src/api/** - "**/*.test.ts" --- # API Rules - Use shared schemas under `src/api/schema/` to validate request bodies. - Every handler must return a standard error structure. ``` You can also directly use `paths` to configure path-based activation: ```markdown theme={null} --- paths: - src/api/** - "**/*.test.ts" --- ``` #### Configurable Frontmatter Options | Option | Available Values | Description | | ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `trigger` | `always_on`, `manual`, `model_decision`, `glob` | Activation method. `always_on` means always active; `manual` means manual inclusion; `model_decision` means model decision and must be set with a non-empty `description`; `glob` means specific files and must be set with a valid `glob`. | | `alwaysApply` | `true`, `false` | Compatibility configuration. `true` is equivalent to `trigger: always_on`; `false` is equivalent to `trigger: manual`. | | `description` | String | Description for model decision rules, helping the model determine whether to read the rule body. | | `glob` | Single glob or list of globs | Used with `trigger: glob` to specify the file scope where the rule applies. | | `paths` | Single glob or list of globs | Specifies the file scope where the rule applies, behaving equivalently to `trigger: glob` + `glob`. | Regarding `glob` and `paths`: * Both accept a set of glob patterns. For project-level rules, globs are matched relative to the project directory containing the `.qoder/` directory; for User-Level rules, globs are matched relative to the current project root directory. * Both are internal routing metadata: they only determine when a rule takes effect and are not injected into the model context along with the rule body. Patterns use gitignore-style matching. Common examples: | Pattern | Matches | | ---------------------- | --------------------------------------------------------- | | `**/*.ts` | All TypeScript files in any directory | | `src/**/*` | All files at any depth under `src/` | | `*.md` | Markdown files in any directory | | `/*.md` | Markdown files only in the project root directory | | `src/components/*.tsx` | Files directly under `src/components/` (excluding nested) | #### Updating Rules During a Session Once a rule is loaded, Qoder CLI continuously monitors the file for the remainder of the session. Edits to rules (regardless of how they were loaded, or whether they are project-level or User-Level) are detected in the next turn, allowing you to adjust rules on the fly and have Qoder CLI follow the new version without restarting. Path-based rules are also added to the monitoring list when they first match an accessed file. ### Writing Recommendations Treat `AGENTS.md` as "facts and conventions to know for the next session." Suitable content includes: * Build, test, formatting, and release commands * Project directory structure and key module boundaries * Code style, naming conventions, and review requirements * Team-agreed workflows, such as commits, branching, and test data preparation * Long-term security or compliance considerations for the current repository Unsuitable content includes: * Temporary states useful only for the current task * Schedules and progress that will quickly expire * Lengthy repetitive content already evident from the code or README * Security policies that must be strictly enforced. Such requirements should be placed in permission configuration or Hooks The more specific and stable the instructions, the better. For example: ```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/`. ``` ### Importing Other Files `AGENTS.md` can use `@path/to/file` to import other files. Relative paths are resolved based on the directory containing the current `AGENTS.md`. ```markdown theme={null} # Project Notes See @README.md for the high-level architecture. Use @docs/testing.md for test data setup. ``` Import rules: * Supports relative paths, absolute paths, and `~/` paths. * `@...` inside Markdown inline code and code blocks are not treated as imports. * Project and local project level memory only allow importing files within the project boundaries by default; imports pointing outside the project require explicit approval or allowance via security settings. * Imports are expanded recursively with a depth limit to prevent infinite expansion from circular imports. If you just want to mention `@README.md` in the text, write it as `` `@README.md` ``. ## Auto-Memory When Auto-Memory is enabled, Qoder CLI saves information worth reusing across sessions as local Markdown files during conversations. It does not save every conversation snippet, but rather judges whether the content is worth remembering. ### Suitable Content to Save Auto-Memory supports four types of content: | Type | Purpose | | ----------- | ------------------------------------------------------------------------------------------------------------------ | | `user` | User roles, long-term preferences, cross-project working habits | | `feedback` | User corrections or confirmations on working methods, e.g., "don't do this in the future" | | `project` | Background, constraints, or decision reasons in the current project that cannot be directly inferred from the code | | `reference` | Locations of external systems, Kanban boards, dashboards, documentation, and other resources | Auto-Memory consists of local files and will not automatically sync to other machines when code is committed. It may also become outdated; when memory involves files, functions, configurations, or external states, Qoder CLI should verify current facts before acting upon it. ### Enabling Auto-Memory Auto-Memory only runs in interactive sessions. The current implementation uses Environment Variables as the effective switch: ```bash theme={null} QODER_MEMORY=1 qodercli ``` If you also want to enable the cross-project User-Level Auto-Memory root directory, set the following simultaneously: ```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` will prompt that Auto-Memory is unavailable. ### Auto-Memory Storage Locations project-level Auto-Memory is saved in the Qoder configuration directory corresponding to the current project: ```text theme={null} ~/.qoder/projects//memory/ ``` When User-Level Auto-Memory is enabled, the following is also used: ```text theme={null} ~/.qoder/memory/ ``` Each Auto-Memory directory contains a `MEMORY.md` index and several topic files: ```text theme={null} memory/ ├── MEMORY.md ├── user-preferences.md ├── feedback-testing.md └── project-release-context.md ``` `MEMORY.md` serves as the index and should not contain lengthy body text. When starting, Qoder CLI reads the `MEMORY.md` of each active Auto-Memory root, reading up to the first 200 lines or about 25KB. More detailed content should be placed in separate topic files and referenced by the index. ## Viewing and Managing In the TUI, enter: ```text theme={null} /memory ``` `/memory` opens the Memory Overview, displaying User-Level, project-level, and local project level memory files, and shows the `Open auto-memory folder` entry when Auto-Memory is enabled. Selecting this entry opens the corresponding auto-memory folder using the system file manager. To manage Auto-Memory by topic files within the TUI: ```text theme={null} /memory manage ``` `/memory manage` opens the Auto-Memory Manager, where you can view, open, edit, or delete Auto-Memory topic files. When deleting a topic file, Qoder CLI synchronously removes the corresponding `MEMORY.md` index line. ### Making Qoder CLI Remember or Forget You can express this directly in natural language: ```text theme={null} Remember to start a local Redis server before running the integration tests for this project. ``` Or: ```text theme={null} Forget previous memory about the old deployment script. ``` If the content is more like team rules or project instructions, it is recommended to explicitly request writing to `AGENTS.md`: ```text theme={null} Add this test convention to the project AGENTS.md. ``` ## Troubleshooting ### Qoder CLI is not following `AGENTS.md` * Run `/memory` to confirm the target file appears in the list. * Ensure the current directory is within a Trusted Workspace; untrusted directories will not load project settings, Hooks, MCP, and `AGENTS.md`. * Check for conflicting instructions, especially between User-Level, project-level, and local project level files. * Check if `agentsMdExcludes` excludes the target file. * Change vague requirements into specific, verifiable rules. ### `@` imports are not taking effect * Confirm the path actually exists and is not written inside a Markdown code block or inline code. * Imports from outside the project are blocked by default; you need to approve external imports or adjust security settings. * For npm package names, general mentions, and `@word` without file characteristics, Qoder CLI will not process them as file imports. ### Auto-Memory is not appearing * Ensure you are currently in a TUI interactive session. * Confirm that `QODER_MEMORY=1` was set at startup. * Run `/memory` to see if the auto-memory folder entry appears; or run `/memory manage` to check if the Auto-Memory Manager is available. * Memory is not saved in every turn; creating 0 memory entries is a normal result when there is no information worth reusing across sessions. ### Memory content is outdated Memory reflects the context at the time it was written. When dealing with current code, configurations, or external system states, rely on the current files and current system; if you find that memory is outdated, update or delete the corresponding memory.