Memory - Qoder CN

Qoder CN provides a long-term memory capability. During conversations between a developer and Qoder CN, it gradually builds a rich memory related to the developer, their projects, and their problems, and automatically organizes and updates this memory. This memory capability helps Qoder CN interact better with developers, and over time, allows Qoder CN to understand them better and better. Qoder CN CLI reconstructs its context for every session. Knowledge that needs to persist across sessions comes mainly from two kinds of memory: AGENTS.md files (persistent instructions maintained by you or your team, suited to development conventions, project structure, common commands, and collaboration agreements) and auto-memory (Markdown memory saved locally by Qoder CN CLI once enabled, suited to 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. When you need to hard-block a certain kind of command, tool, or path, use Permissions configuration or Hooks.

Memory Types

Mechanism	Who writes it	Suitable content	Scope	Entry point
`AGENTS.md`	User or team	Clear, stable instructions you want followed in every session	User-level, project-level, local project-level, plugin-provided	`/memory`
Auto-memory	Qoder CN CLI	Reusable information learned from the conversation, such as preferences, feedback, project background, and locations of external materials	Project-level; optionally user-level	`/memory` opens the auto-memory folder; `/memory manage` manages topic files

AGENTS.md

AGENTS.md is the default context file name in Qoder CN CLI. When starting or refreshing memory, Qoder CN CLI reads the available AGENTS.md files and injects their 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`	Cross-project general preferences and working habits for the current user	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 to use a different file name, you can use context.fileName to set a single file name or an array of file names. The default is AGENTS.md.

Loading logic

When starting or refreshing memory, Qoder CN CLI's project memory searches upward and checks the project rules directory at each level:

User-level memory: loads AGENTS.md from the user configuration 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.
Rules without a paths frontmatter are loaded together with project memory; rules with a paths frontmatter are loaded on demand only after Qoder CN CLI accesses a matching file.
Subdirectory memory: not preloaded at startup. Only after Qoder CN CLI successfully reads a file in a subdirectory does it supplement, from that file's directory upward, any previously unloaded AGENTS.md, AGENTS.local.md, or matching .qoder/rules/**/*.md. This on-demand content enters subsequent context and is shown 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 you start from /repo, it will not preload /repo/packages/app/AGENTS.md or /repo/packages/app/.qoder/rules/*.md; these are loaded on demand only after you access files under packages/app.

Rules

Rules are instruction files placed under the rules/ directory and split by topic, used to replace a single bloated AGENTS.md. You can split them by topic (testing, API, security) or by the code area they govern. Each rule is an ordinary Markdown file; an optional paths frontmatter determines when it takes effect.

Where to store them

Rules have two scopes:

Scope	Location	Effective range	Committed
Project-level	`<project>/.qoder/rules/*/.md`	The project the file resides in, shared with the team	Yes
User-level	`~/.qoder-cn/rules/*/.md`	Every project you open, for personal use on this machine only	No

Project-level rules can reside 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 configuration directory and apply to all projects.

Always effective vs. path-based

A rule's optional paths frontmatter determines when it is loaded:

No paths frontmatter: the rule is always effective. It is eager-loaded at startup------project-level rules load with the project layer, user-level rules load with the user layer.
With paths frontmatter: the rule is path-based. It is loaded on demand only after Qoder CN CLI accesses a file whose path matches one of the globs.

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

# API Rules

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

About paths:

It is a set of glob patterns. For project-level rules, globs match relative to the project directory containing the .qoder/ directory; for user-level rules, globs match relative to the current project root.
A rule that uses only ** (match everything) is treated as always effective.
paths is internal routing metadata: it only determines when a rule takes effect and is not injected into the model context------only the rule body is injected.

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/` (not nested)

Updating rules during a session

Once a rule is loaded, Qoder CN CLI keeps watching that file for the rest of the session. Editing a rule (whether always effective or path-based, project-level or user-level) is picked up on the next turn, so you can adjust rules on the fly and have Qoder CN CLI follow the new version without restarting. A path-based rule is also added to the watch when it first matches an accessed file.

Writing recommendations

Treat AGENTS.md as "facts and conventions you'll still need to know next session." Good things to write:

Build, test, format, and release commands
Project directory structure and key module boundaries
Code style, naming rules, and review requirements
Team-agreed workflows, such as commits, branching, and test data preparation
Security or compliance notes that remain valid long-term for the current repository

Not suitable to write:

Temporary state useful only for the current task
Schedules and progress that will soon become outdated
Lengthy, repetitive content already evident directly from the code or README
Security policies that must be enforced. Such requirements belong in Permissions 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:

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 by default only allow importing files within the project boundary; imports pointing outside the project require explicit approval or must be allowed by security settings.
Imports are expanded recursively, with a depth limit to prevent circular imports from expanding infinitely.

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

Auto-memory

Once auto-memory is enabled, Qoder CN CLI saves information worth reusing across sessions as local Markdown files during the conversation. It does not save every part of the conversation; instead, it judges based on content whether something is worth remembering.

Content suited to saving

Auto-memory supports four kinds of content:

Type	Purpose
`user`	User role, long-term preferences, cross-project working habits
`feedback`	User corrections or confirmations about how you work, such as "don't do this in the future"
`project`	Background, constraints, or reasons for decisions in the current project that cannot be derived directly from the code
`reference`	Locations of external systems, boards, dashboards, documentation, and other materials

Auto-memory consists of local files and is not automatically synced to other machines by committing code. It can also become outdated; when a memory involves files, functions, configuration, or external state, Qoder CN CLI should first 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:

QODER_MEMORY=1 qoderclicn

If you also want to enable the cross-project user-level auto-memory root, set both:

QODER_MEMORY=1 QODER_MEMORY_USER=1 qoderclicn

QODER_MEMORY_USER takes effect only when QODER_MEMORY is already enabled. When auto-memory is not enabled, /memory can still manage AGENTS.md files; /memory manage will indicate that auto-memory is unavailable.

Auto-memory storage location

Project-level auto-memory is saved under the Qoder configuration directory corresponding to the current project:

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

Once user-level auto-memory is enabled, it also uses:

~/.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 contain lengthy body content. At startup, Qoder CN CLI reads the MEMORY.md of each active auto-memory root, up to the first 200 lines or about 25KB. More detailed content should go in separate topic files that the index points to.

Viewing and Managing

In the TUI, enter:

/memory

/memory opens the memory overview, showing user-level, project-level, and local project-level memory files, and, when auto-memory is enabled, shows an Open auto-memory folder entry. Selecting that entry 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 you delete a topic file, Qoder CN CLI also removes the corresponding line in the MEMORY.md index.

Asking Qoder CN CLI to remember or forget

You can express this directly in natural language:

Remember that this project's integration tests require starting a 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, we recommend explicitly asking to write it to AGENTS.md:

Add this testing convention to the project AGENTS.md.

Troubleshooting

Qoder CN CLI is not following AGENTS.md

Run /memory and confirm the target file appears in the list.
Confirm the current directory is within a trusted workspace; untrusted directories do not load project settings, Hooks, MCP, or AGENTS.md.
Check for conflicting instructions, especially conflicts between user-level, project-level, and local project-level files.
Check whether agentsMdExcludes excludes the target file.
Change vague requirements into specific, verifiable rules.

@ import is 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; you need to approve external imports or adjust security settings.
For npm package names, plain mentions, and @word without file-like characteristics, Qoder CN CLI does not treat them as file imports.

Auto-memory does not appear

Confirm you are in a TUI interactive session.
Confirm QODER_MEMORY=1 was set at startup.
Run /memory to 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 a memory; when there is no information worth reusing across sessions, creating 0 memories is a normal result.

Memory content is outdated

Memory reflects the context at the time it was written. When working with current code, configuration, or external system state, rely on the current files and current system; if you find a memory is outdated, update or delete the corresponding memory.

​Memory Types

​AGENTS.md

​Common locations

​Loading logic

​Rules

​Where to store them

​Always effective vs. path-based

​Updating rules during a session

​Writing recommendations

​Importing other files

​Auto-memory

​Content suited to saving

​Enabling auto-memory

​Auto-memory storage location

​Viewing and Managing

​Asking Qoder CN CLI to remember or forget

​Troubleshooting

​Qoder CN CLI is not following AGENTS.md

​@ import is not taking effect

​Auto-memory does not appear

​Memory content is outdated