Skip to main content
Qoder CLI rebuilds context for every session. Knowledge that should carry across sessions comes from two memory systems:
  • AGENTS.md files: durable instructions maintained by you or your team, 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

MechanismWritten byBest forScopeView with
AGENTS.mdYou or your teamExplicit, stable instructions to apply every sessionUser, project, local project, plugin-provided/memory
Auto-memoryQoder CLIReusable learnings from conversation, such as preferences, feedback, project background, and referencesProject; optional user scope/memory opens the auto-memory folder; /memory manage manages topic files

​
AGENTS.md

AGENTS.md is the default context file name in Qoder CLI. When memory is loaded or refreshed, Qoder CLI reads available AGENTS.md files and injects their content as session context.

​
Common Locations

~/.qoder/AGENTS.md
<project>/AGENTS.md
<project>/AGENTS.local.md
LocationPurposeCommit it?
~/.qoder/AGENTS.mdCross-project preferences and personal workflow habits for the current userNo
<project>/AGENTS.mdTeam-shared project rules, architecture notes, and common commandsYes
<project>/AGENTS.local.mdMachine-local project notes, such as local URLs or personal test dataNo
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 only searches upward for project memory. It does not scan child directories:
  • 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 and AGENTS.local.md, stopping by default at the directory containing .git.
  • 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 or AGENTS.local.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/AGENTS.md
/repo/AGENTS.md
Starting in /repo does not preload /repo/packages/app/AGENTS.md; it is loaded on demand only after Qoder CLI accesses a file under packages/app.

​
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:
TypeUse
userUser role, long-term preferences, and cross-project habits
feedbackCorrections or confirmations about how Qoder CLI should work with you
projectProject background, constraints, or decision reasons not directly derivable from code
referenceLocations 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.