Skip to main content

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 exists​

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 structure​

.dmx/
├── config.md           # Project configuration (set by /dmx/init)
├── projectbrief.md      # Project goals and scope
├── productContext.md    # User-facing behaviour 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
├── loops/              # Custom loop configs (optional)
│   └── *.yaml
├── jobs/               # Loop execution records
│   └── {job_id}/
│       └── {loop}-{task_id}.json
├── loop-state.json     # Active loop pointer
└── releases/           # Drafted release notes (optional)
    └── {version}.md

Core memory files​

config.md​

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.

projectbrief.md​

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.md​

User-facing behaviour 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/update-memory when features ship that change user-facing behaviour.

systemPatterns.md​

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.md​

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.

Maintained automatically by /dmx/update-memory and updated during /dmx/commit.

activeContext.md​

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/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 files​

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 bank​

The memory bank updates happen at two points:

Automatically: /dmx/commit appends light progress notes to activeContext.md after each phase; the loop runtime appends a one-line breadcrumb to activeContext.md's Session Notes at the end of every loop run. /dmx/update-memory (called by the Release Loop) distils these into the permanent files.

On demand: run /dmx/update-memory at any time to trigger a full memory bank update from the current session's learnings:

/dmx/update-memory

Committing .dmx/ to the repo​

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)
  • spec.md and tasks.md on feature branches

Optionally gitignore:

  • jobs/: loop execution records can get large over time. Many teams commit them for auditability; others gitignore them.
  • loop-state.json: the active pointer. Safe to commit; resolves automatically on checkout.

A reasonable .gitignore entry if you want to prune old job records:

# Keep job records but exclude from default diffs
.dmx/jobs/

Tips​

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.