Memory - Qoder CN

Qoder CLI CN reconstructs its context for every session. Knowledge that needs to be retained across sessions comes mainly from two kinds of memory:

Static memory: durable instructions maintained by you or your team, including AGENTS.md and rules — good for development standards, project structure, common commands, and collaboration conventions.
Auto-memory: Markdown memory saved locally by Qoder CLI CN when enabled — good for recording preferences, feedback, project background, and external references that remain useful in later sessions.

Memory is provided to the model as context, but it is not enforced policy. To hard-block certain commands, tools, or paths, use permission configuration or Hooks.

Memory types

Mechanism	Written by	Best for	Scope	Where to view
Static memory	User or team	Explicit, stable instructions to follow in every session; `AGENTS.md` for the overall description, rules split by topic or file scope	User, project, local project, plugin-provided	`/memory`
Auto-memory	Qoder CLI CN	Reusable information learned from conversations, such as preferences, feedback, project background, locations of external material	Project level; optional user level	`/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. AGENTS.md suits the overall project description and stable conventions; rules suit splitting similar instructions into multiple Markdown files by topic or file scope.

Static memory files

AGENTS.md is Qoder CLI CN's default context file name, and rules are Markdown rule files under a rules/ directory. At startup or on memory refresh, Qoder CLI CN reads the available static memory files and injects the matching content into the session as context.

Common locations

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

Location	Purpose	Suitable to commit
`~/.qoder-cn/AGENTS.md`	The current user's cross-project preferences and working habits	No
`<project>/AGENTS.md`	Team-shared project rules, architecture notes, common commands	Yes
`<project>/AGENTS.local.md`	Project-private notes 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 a different file name, set a single file name or an array of file names with context.fileName. The default is AGENTS.md.

Loading logic

At startup or on memory refresh, Qoder CLI CN's project memory searches upward, checking each level's project rules directory:

User-level memory: loads AGENTS.md from the user config directory.
Project and local project memory: within a trusted workspace, searches from the current workspace directory up through parent directories for AGENTS.md, AGENTS.local.md, and .qoder/rules/**/*.md, stopping by default at the directory containing .git.
A rule's frontmatter determines how it loads: always-on rules load along with project memory; file-scoped rules load on demand only after Qoder CLI CN accesses a matching file; manual rules and model-decision rules do not inject their bodies at startup.
Subdirectory memory: not preloaded at startup. Only after Qoder CLI CN successfully reads a file in a subdirectory does it supplement, from that file's directory upward, any AGENTS.md, AGENTS.local.md, or matching .qoder/rules/**/*.md not loaded before. This on-demand content enters subsequent context and shows up in /memory.

For example, when starting in /repo/packages/app, these are checked:

/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

When starting from /repo, /repo/packages/app/AGENTS.md and /repo/packages/app/.qoder/rules/*.md are not preloaded; they load on demand after files under packages/app are accessed.

Rules

Rules are instruction files under a rules/ directory, split by topic, replacing a single bloated AGENTS.md. Split them by topic (testing, API, security) or by the code area they govern. Each rule is a plain Markdown file; optional frontmatter decides when it takes effect. Qoder CLI CN's rules frontmatter is compatible with the rules settings configured in Qoder Desktop; rule files synced or copied from Qoder Desktop keep their original trigger configuration.

Locations

Rules have two scopes:

Scope	Location	Applies to	Commit
Project	`<project>/.qoder/rules/*/.md`	The project containing the file, shared with the team	Yes
User	`~/.qoder-cn/rules/*/.md`	Every project you open, personal to this machine	No

Project-level rules can live at any level of the workspace (including nested subdirectories) and are discovered by searching upward from the working directory. User-level rules are read from the user config directory and apply to all projects.

Supported activation modes

Qoder CLI CN supports four rules activation modes. Without loading-related frontmatter, a rule defaults to always-on; when trigger is present, it takes precedence over alwaysApply.

Mode	Best for	Configuration	Loading behavior
Always on	General rules to follow in every session	No loading frontmatter, or `trigger: always_on`, or `alwaysApply: true`	The rule body loads at startup or on memory refresh.
Manual	Occasionally used rules that must be pulled in explicitly	`trigger: manual` or `alwaysApply: false`	The rule body is not injected automatically.
Model decision	Rules whose relevance can be judged from a one-line description	`trigger: model_decision` + a non-empty `description`	Only the rule path and description are injected; the body is read when the model judges it relevant.
File-scoped	Rules that apply only to certain files or directories	`trigger: glob` + `glob`, or `paths` directly	The rule body loads on demand after Qoder CLI CN accesses a matching file.

trigger: model_decision requires a non-empty description; trigger: glob requires a valid glob. When a required field is missing, the rule body is not injected into context automatically.

Configuration examples

An always-on rule can omit frontmatter, or set it explicitly:

---
trigger: always_on
---

# General project conventions

- Run tests before committing.
- Update docs when changing public APIs.

A manual rule is not injected into context automatically:

---
trigger: manual
---

# Release checklist

- Confirm the version number is updated.
- Confirm the changelog is filled in.

A model-decision rule needs a description used to judge whether to read the rule body:

---
trigger: model_decision
description: Use when modifying API handlers, schemas, or interface error structures.
---

# API rules

- Validate request bodies with the shared schemas under `src/api/schema/`.
- Every handler must return the standard error structure.

For file-scoped rules, use trigger: glob + glob:

---
trigger: glob
glob:
  - src/api/**
  - "**/*.test.ts"
---

# API rules

- Validate request bodies with the shared schemas under `src/api/schema/`.
- Every handler must return the standard error structure.

You can also use paths directly for path-based activation:

---
paths:
  - src/api/**
  - "**/*.test.ts"
---

Frontmatter options

Option	Values	Description
`trigger`	`always_on`, `manual`, `model_decision`, `glob`	Activation mode. `always_on` means always in effect; `manual` means pulled in manually; `model_decision` means model-decided and requires a non-empty `description`; `glob` means file-scoped and requires a valid `glob`.
`alwaysApply`	`true`, `false`	Compatibility option. `true` is equivalent to `trigger: always_on`; `false` is equivalent to `trigger: manual`.
`description`	string	Description for model-decision rules, helping the model judge whether to read the rule body.
`glob`	a single glob or a list of globs	Paired with `trigger: glob` to specify the file scope where the rule applies.
`paths`	a single glob or a list of globs	Specifies the file scope where the rule applies; behaves the same as `trigger: glob` + `glob`.

About glob and paths:

Both accept a set of glob patterns. Project-level rule globs match relative to the project directory containing the .qoder/ directory; user-level rule globs match relative to the current project root.
Both are internal routing metadata: they only decide 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 in the project root only
`src/components/*.tsx`	Files directly under `src/components/` (no nesting)

Updating rules within a session

Once a rule loads, Qoder CLI CN keeps watching that file for the rest of the session. Editing a rule (regardless of how it loaded, project- or user-level) is picked up on the next turn, so you can adjust rules on the fly and have Qoder CLI CN follow the new version without restarting. File-scoped rules are also brought under watch the first time they match an accessed file.

Writing advice

Treat AGENTS.md as "facts and conventions the next session should still know." Good things to write:

Build, test, formatting, and release commands
Project directory structure and key module boundaries
Code style, naming rules, and review requirements
Team workflows, such as commits, branching, and test data preparation
Security or compliance notes with long-term validity for this repository

Not suitable:

Temporary state useful only for the current task
Schedules and progress that will soon be stale
Long repetitive content already evident from the code or README
Security policies that must be enforced — put those in permission configuration or Hooks

The more specific the instruction, the more stable it is. 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 pull in other files with @path/to/file. Relative paths resolve from 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:

Relative paths, absolute paths, and ~/ paths are supported.
@... inside Markdown inline code and code blocks is not treated as an import.
Project and local project memory only allow imports within the project boundary by default; imports pointing outside the project require explicit approval or must be allowed via security settings.
Imports expand recursively with a depth limit, preventing infinite expansion from circular imports.

If you just want to mention @README.md in text, write it as `@README.md`.

Auto-memory

With auto-memory enabled, Qoder CLI CN saves information worth reusing across sessions into local Markdown files during conversations. It does not save every exchange — it judges from the content whether something is worth remembering.

What it saves

Auto-memory supports four kinds of content:

Type	Purpose
`user`	User role, long-term preferences, cross-project working habits
`feedback`	The user's corrections or confirmations about how to work, e.g. "don't do this again"
`project`	Background, constraints, or decision rationale in the current project that cannot be derived directly from the code
`reference`	Locations of external systems, boards, dashboards, documents, and other material

Auto-memory consists of local files and does not sync automatically to other machines through code commits. It can also go stale; when a memory involves files, functions, configuration, or external state, Qoder CLI CN should verify the current facts before acting on it.

Enabling auto-memory

Auto-memory runs only in interactive sessions. The current implementation uses an environment variable as the effective switch:

QODERCN_MEMORY=1 qodercn

To also enable the cross-project user-level auto-memory root, set additionally:

QODERCN_MEMORY=1 QODERCN_MEMORY_USER=1 qodercn

QODERCN_MEMORY_USER only takes effect when QODERCN_MEMORY is already enabled. With auto-memory disabled, /memory can still manage AGENTS.md files; /memory manage reports that auto-memory is unavailable.

Auto-memory storage locations

Project-level auto-memory is stored under the Qoder config directory corresponding to the current project:

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

With user-level auto-memory enabled, this is also used:

~/.qoder-cn/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 is an index and should not hold long-form content. At startup, Qoder CLI CN reads the MEMORY.md of each active auto-memory root, up to the first 200 lines or about 25KB. More detailed content belongs in separate topic files that the index points to.

Viewing and managing

Type in the TUI:

/memory

/memory opens the memory overview, showing user-level, project-level, and local project-level memory files, and — with auto-memory enabled — an Open auto-memory folder entry. Selecting it opens the corresponding auto-memory folder in the system file manager. To manage auto-memory by topic file 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 a topic file is deleted, Qoder CLI CN also removes the corresponding index line from MEMORY.md.

Asking Qoder CLI CN to remember or forget

You can say it directly in natural language:

Remember that this project's integration tests require starting local Redis first.

Or:

Forget the earlier memory about the old deployment script.

If the content is more like a team rule or project instruction, explicitly ask for it to be written into AGENTS.md:

Add this testing convention to the project AGENTS.md.

Troubleshooting

Qoder CLI CN is not following `AGENTS.md`

Run /memory and confirm the target file appears in the list.
Confirm the current directory is inside a trusted workspace; untrusted directories do not load project settings, Hooks, MCP, or AGENTS.md.
Check for conflicting instructions, especially conflicts among user-level, project-level, and local project-level files.
Check whether agentsMdExcludes excludes the target file.
Turn vague demands 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 outside the project are blocked by default; approve the external import or adjust the security settings.
Qoder CLI CN does not treat npm package names, plain mentions, or @word without file characteristics as file imports.

Auto-memory does not appear

Confirm you are in an interactive TUI session.
Confirm QODERCN_MEMORY=1 was set at startup.
Run /memory and check whether the auto-memory folder entry appears; or run /memory manage to check whether the auto-memory manager is available.
Not every turn saves memory; creating 0 memories is a normal outcome when there is nothing worth reusing across sessions.

Memory content is stale

Memory reflects the context at the time it was written. When working with current code, configuration, or external system state, the current files and systems are the source of truth; if a memory turns out to be stale, update or delete it.

​Memory types

​Static memory

​Static memory files

​Common locations

​Loading logic

​Rules

​Locations

​Supported activation modes

​Configuration examples

​Frontmatter options

​Updating rules within a session

​Writing advice

​Importing other files

​Auto-memory

​What it saves

​Enabling auto-memory

​Auto-memory storage locations

​Viewing and managing

​Asking Qoder CLI CN to remember or forget

​Troubleshooting

​Qoder CLI CN is not following AGENTS.md

​@ imports are not taking effect

​Auto-memory does not appear

​Memory content is stale