MD Files

Agent and team configuration files — IDENTITY, INSTRUCTIONS, KNOWLEDGE, GOALS, CONTEXT, RULES

The MdFilesService (apps/api/src/memory/md-files.service.ts) manages structured markdown configuration files for agents and teams. These files form the foundation of pipeline/context-assembly|Layer 1 and Layer 2 context.

Agent Files

Each agent has three configuration files:

File Key	Purpose	Context Layer
`IDENTITY`	Who the agent is — personality, role, voice	L1 (never truncated)
`INSTRUCTIONS`	How the agent should behave — rules, constraints	L1 (never truncated)
`KNOWLEDGE`	Domain reference material — facts, procedures	L7 (2000 token budget)

Auto-Provisioning

When ensureAgentMdFiles() is called (during pipeline/context-assembly), it checks if files exist. If not:

Looks up the agent's legacy instructions column
Creates all three files, migrating instructions content to INSTRUCTIONS
Leaves IDENTITY and KNOWLEDGE empty for user customization

This lazy migration ensures backward compatibility with agents created before the MD files system.

Team Files

Each team has three configuration files:

File Key	Purpose	Context Layer
`GOALS`	What the team is trying to achieve	L2
`CONTEXT`	Background information and shared understanding	L2
`RULES`	Team-specific behavioral constraints	L2

Team files are initialized empty via initTeamMdFiles() when a team is created.

Versioning

Both agent and team files are versioned:

Column	Type	Description
`version`	`integer`	Incremented on each update (starts at 1)
`updated_by`	`varchar`	`user` or `system`
`updated_at`	`timestamp`	Last modification time

The upsertAgentMdFile() and upsertTeamMdFile() methods handle insert-or-update logic, incrementing the version on each update.

Database Tables

Agent files are stored in agent_md_files:

agent_id (FK → agents, CASCADE)
file_key (IDENTITY, INSTRUCTIONS, KNOWLEDGE)
content (text)
Unique constraint on (agent_id, file_key)

Team files are stored in team_md_files:

team_id (FK → teams, CASCADE)
file_key (GOALS, CONTEXT, RULES)
content (text)
Unique constraint on (team_id, file_key)

pipeline/context-assembly — How MD files are loaded into agent context
schema/types — Database table definitions
operations/configuration — Token budgets for each file type