Memory - Qoder

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

~/.qoder/AGENTS.md
<project>/AGENTS.md
<project>/AGENTS.local.md
<project>/.qoder/rules/**/*.md

Location	Purpose	Suitable to Commit
`~/.qoder/AGENTS.md`	Cross-project general preferences and working habits for the current user	No
`<project>/AGENTS.md`	Team-shared project rules, architecture instructions, and common commands	Yes
`<project>/AGENTS.local.md`	Project-private instructions on the current machine, such as local service addresses or personal test data	No
`<project>/.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:

/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	`<project>/.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:

---
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:

---
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:

---
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:

---
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:

---
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:

# 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.

# 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:

QODER_MEMORY=1 qodercli

If you also want to enable the cross-project User-Level Auto-Memory root directory, set the following simultaneously:

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:

~/.qoder/projects/<project>/memory/

When User-Level Auto-Memory is enabled, the following is also used:

~/.qoder/memory/

Each Auto-Memory directory contains a MEMORY.md index and several topic files:

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:

/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:

/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:

Remember to start a local Redis server before running the integration tests for this project.

Or:

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:

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.

​Memory Types

​Static Memory

​Static Memory Files

​Common Locations

​Loading Logic

​Rules

​Storage Locations

​Supported Activation Methods

​Configuration Examples

​Configurable Frontmatter Options

​Updating Rules During a Session

​Writing Recommendations

​Importing Other Files

​Auto-Memory

​Suitable Content to Save

​Enabling Auto-Memory

​Auto-Memory Storage Locations

​Viewing and Managing

​Making Qoder CLI Remember or Forget

​Troubleshooting

​Qoder CLI is not following AGENTS.md

​@ imports are not taking effect

​Auto-Memory is not appearing

​Memory content is outdated