Memory

Memory is the set of instruction files Cusp loads into every session: how to build and test the project, conventions to follow, things to avoid. You write them once and every session, in every surface and with every model, starts with them.

Cusp reads the instruction files of other agents too, so a repository that already has a CLAUDE.md or an AGENTS.md works without changes.

File namesCopy Anchor Link

At each directory level, Cusp looks for these files and loads every one that exists, in this order:

Later files carry more weight. When two files give conflicting guidance, the one loaded later wins, so CUSP.md overrides CLAUDE.md, which overrides AGENTS.md.

If you are starting fresh, write a CUSP.md, or run /init and let Cusp draft one. If your team also uses other agents, keep the shared guidance in AGENTS.md and put anything Cusp-specific in CUSP.md.

Where Cusp looksCopy Anchor Link

Instructions load from several scopes, broadest first:

1. Managed. Organization-wide files set by an administrator:

   Platform	Paths
   macOS	/Library/Application Support/ClaudeCode/CLAUDE.md, /Library/Application Support/Cusp/CUSP.md
   Windows	C:\Program Files\ClaudeCode\CLAUDE.md, C:\Program Files\Cusp\CUSP.md
   Linux	/etc/claude-code/CLAUDE.md, /etc/cusp/CUSP.md

2. User. Your personal preferences, for every project: ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md and ~/.cusp/CUSP.md, plus rules in ~/.claude/rules/ and ~/.cusp/rules/.

3. Project. Every directory from the filesystem root down to your working directory, root first, so the instructions closest to where you work come last. Plus rules in .claude/rules/ and .cusp/rules/ at the project root.

4. Local. CLAUDE.local.md and CUSP.local.md: personal notes for this project that you don't commit. Add them to .gitignore.

Nested directoriesCopy Anchor Link

Instruction files in subdirectories below your working directory load lazily. When the agent first reads or edits a file in packages/api/, Cusp loads packages/api/CUSP.md (or AGENTS.md, CLAUDE.md, …) at that moment. In a monorepo, this keeps each package's guidance out of context until it's relevant.

RulesCopy Anchor Link

Rules are small instruction files in a rules/ directory, one topic per file. A rule without frontmatter loads at session start like any other instruction file.

A rule with paths: loads only when the agent touches a matching file:

---
paths:
  - "db/migrations/**"
  - "**/*.sql"
---

Migrations are append-only. Never edit a migration that has been merged; add a new one.
Run `bun run db:check` after writing a migration.

This is the best place for guidance that matters for one area of the codebase and would be noise everywhere else.

ImportsCopy Anchor Link

An instruction file can pull in another file with @path:

# Project guide

See @docs/architecture.md for the module layout.
Coding conventions: @docs/conventions.md

• Paths are relative to the file that contains the import. ~/ paths work too.
• Imports can nest up to 4 levels deep. Cycles are detected and skipped.
• @path inside code blocks and inline code is ignored, so examples don't trigger imports.

What gets strippedCopy Anchor Link

• Block HTML comments (<!-- … -->) are removed before the content reaches the model. Use them for notes to human maintainers.
• YAML frontmatter on rules is removed after Cusp reads paths:.
• Files larger than 4 MiB are skipped with a warning.

Excluding filesCopy Anchor Link

If a file shouldn't load, for example a vendored package's AGENTS.md written for a different project, exclude it in settings:

{
  "claudeMdExcludes": ["vendor/**", "third_party/**/AGENTS.md"]
}

Managed files can't be excluded.

Writing good instructionsCopy Anchor Link

Instruction files cost context in every session, so keep them short and concrete.

• Lead with commands. How to install, build, run tests, lint and typecheck. These are what the agent needs most often.
• State conventions as rules. "Use zod for validation; never hand-write type guards for API input" beats a paragraph on philosophy.
• Name the gotchas. The flaky test, the generated file nobody should edit, the environment variable that must be set.
• Point, don't paste. Link to architecture docs with @path instead of copying them in.
• Move area-specific guidance into path-scoped rules.

A useful CUSP.md is often under 100 lines.

The /init commandCopy Anchor Link

/init asks the agent to analyze the codebase and write a CUSP.md at the repository root covering build, test and lint commands, an architecture overview, key conventions and gotchas. If CUSP.md, AGENTS.md or CLAUDE.md already exists, it improves that file instead of starting over. Review the result like any other change.