Memory - Qoder

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

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

Location	Purpose	Commit it?
`~/.qoder/AGENTS.md`	Cross-project preferences and personal workflow habits for the current user	No
`<project>/AGENTS.md`	Team-shared project rules, architecture notes, and common commands	Yes
`<project>/AGENTS.local.md`	Machine-local project notes, such as local URLs or personal test data	No
`<project>/.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:

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

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

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

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

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

---
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`.
`alwaysApply`	`true`, `false`	Compatibility setting. `true` is equivalent to `trigger: always_on`; `false` is equivalent to `trigger: manual`.
`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:

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

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

QODER_MEMORY=1 qodercli

To also enable the cross-project user-scope auto-memory root:

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:

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

When user-scope auto-memory is enabled, Qoder CLI also uses:

~/.qoder/memory/

Each auto-memory directory contains a MEMORY.md index and optional topic files:

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:

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

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

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

Or:

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:

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.

​Memory Types

​Static Memory

​Static Memory Files

​Common Locations

​Loading Logic

​Rules

​Where Rules Live

​Supported Activation Modes

​Configuration Examples

​Frontmatter Options

​Updating Rules Mid-Session

​Writing Good Instructions

​Import Other Files

​Auto-Memory

​What Auto-Memory Stores

​Enable Auto-Memory

​Auto-Memory Storage

​View and Manage

​Remember or Forget

​Troubleshooting

​Qoder CLI Is Not Following AGENTS.md

​@ Imports Do Not Load

​Auto-Memory Does Not Appear

​Memory Is Stale