Memory Bank

The memory bank is how dmx gives every AI session the same project context. It's a set of files in .dmx/ committed to your repository.

Why it existsCopy Anchor Link

AI coding assistants are stateless. Every new session starts with no knowledge of your project: its architecture, its conventions, its decisions, its quirks. Developers work around this by pasting context into prompts, maintaining a CLAUDE.md or .cursorrules file, or just repeating themselves.

The dmx memory bank is a structured version of this context, maintained automatically as a side-effect of your workflow.

The .dmx/ directory structureCopy Anchor Link

.dmx/
├── config.md           # Project configuration (set by /dmx/init)
├── projectbrief.md      # Project goals and scope
├── productContext.md    # User-facing behavior and flows
├── systemPatterns.md    # Architecture patterns, conventions
├── techContext.md       # Tech stack, dependencies, build system
├── activeContext.md     # Learning inbox: open learnings, decisions, session notes
├── spec.md             # Current branch spec
├── tasks.md            # Current branch task list
├── shared-sources.yaml # Org-wide shared sources (optional)
├── loops/              # Custom loop configs (optional)
│   └── *.yaml
├── skills/             # Custom skills (optional)
│   └── *.md
├── vendor/             # Vendored shared sources, written by /dmx/sync
│   └── {name}/
├── jobs/               # Loop execution records (also the active-run signal)
│   └── {job_id}/
│       └── {loop}-{task_id}.json
└── releases/           # Drafted release notes (optional)
    └── {version}.md

Core memory filesCopy Anchor Link

config.mdCopy Anchor Link

Set by /dmx/init. Contains your project configuration:

• Workflow mode (Jira / GitHub Issues / none)
• Ticketing system credentials and project key
• Branch naming conventions
• Protected branches
• Tech stack auto-detected from the repository

Re-run /dmx/init to update this file if your configuration changes. To refresh dmx's rule files after upgrading dmx, run /dmx/upgrade instead. See Upgrading dmx.

projectbrief.mdCopy Anchor Link

Project goals and scope: what this project is trying to achieve, and what is and isn't part of it. Written by /dmx/init from your README and project files. Durable — updated rarely, usually only when project goals shift.

productContext.mdCopy Anchor Link

User-facing behavior and flows: why the project exists, how it works from a user's perspective, and who uses it. Written by /dmx/init. Updated by /dmx/create-pr and /dmx/update-memory when features ship that change user-facing behavior.

systemPatterns.mdCopy Anchor Link

Documents architecture decisions, code patterns, and conventions. Examples:

• "We use repository pattern for data access"
• "All API endpoints validate input with Pydantic v2"
• "Tests use pytest fixtures, not setUp/tearDown"
• "Background tasks go in tasks/ and are registered in tasks/__init__.py"

The more specific this file is, the better the AI's output aligns with your existing codebase.

techContext.mdCopy Anchor Link

Describes the tech stack, dependencies, and build system. The AI reads this at the start of every session to understand what libraries are in use, what the test framework is, and how the project is built.

Updated automatically during /dmx/commit and /dmx/create-pr, and reconciled by /dmx/update-memory.

activeContext.mdCopy Anchor Link

The learning inbox — the only branch-local, working-memory file in the core set. It has three sections:

• Open Learnings — observations from the current stretch of work not yet promoted to a durable file
• Open Decisions — unresolved trade-offs or design questions
• Session Notes — a short, rolling log (most recent 10 entries) of what happened recently

Updated automatically by the loop runtime (a one-line breadcrumb after each loop run) and by /dmx/commit (light progress notes). /dmx/create-pr promotes what's left in the inbox before opening the PR. /dmx/update-memory reads the inbox, promotes durable items into systemPatterns.md, techContext.md, or productContext.md as appropriate, and clears what it promotes — it does not write to a separate history file.

Branch-level filesCopy Anchor Link

spec.md and tasks.md are branch-level. They're created for each ticket by create-ticket and used throughout the Spec, Plan, and Dev Loops.

They're committed to the branch, so they're visible to reviewers and persist in the branch history.

Updating the memory bankCopy Anchor Link

The memory bank updates happen at two points:

Automatically: /dmx/commit appends light progress notes to activeContext.md after each phase, and promotes inbox items that are clearly durable (light sync); the loop runtime appends a one-line breadcrumb to activeContext.md's Session Notes at the end of every loop run. /dmx/create-pr (run by the Release Loop) promotes everything remaining in the inbox into the permanent files before opening the PR, and commits the result (full sync).

On demand: run /dmx/update-memory at any time for a deep sync: it reconciles contradictions across the memory files, rebuilds activeContext.md's structure, and commits its own changes:

/dmx/update-memory

Committing .dmx/ to the repoCopy Anchor Link

The entire .dmx/ directory should be committed to your repository, with a few exceptions:

Commit:

• config.md, projectbrief.md, productContext.md, systemPatterns.md, techContext.md, activeContext.md
• loops/ (custom loop configs) and skills/ (custom skills)
• shared-sources.yaml and vendor/, if you use shared sources: loops and validators resolve from the vendored copy, so it has to be in the repo
• spec.md and tasks.md on feature branches

Optionally gitignore:

• jobs/: loop execution records can get large over time. By default the loop runtime commits a run's final state when the run finishes, so the records travel with the PR. Many teams keep them for auditability. A _pending-* folder under jobs/ is always safe to ignore — it's a temporary id the Spec Loop uses before a ticket is created, and it gets renamed away once one is.

To stop committing job records, add them to your .gitignore:

.dmx/jobs/

If job records are already committed, you can untrack them by using:

git rm -r --cached .dmx/jobs/

dmx keeps writing job state to disk, so you can still pause and resume loops on your machine. Teammates and reviewers just won't see the job history.

TipsCopy Anchor Link

Invest in systemPatterns.md. This is the file that most directly improves AI output quality. The more accurately it describes your codebase patterns, the less drift you'll see between the AI's output and your conventions.

Keep activeContext.md's inbox honest. It's meant to be transient — observations waiting to be promoted or discarded, not a permanent log. Run /dmx/update-memory regularly so it doesn't accumulate stale notes.

New developers benefit immediately. When a new developer joins and configures dmx, they get the full team's accumulated context from day one. This is one of the clearest benefits of committing the memory bank.