Institutional Memory Agent

Every team has code nobody wants to touch. This agent makes sure the "why" behind every change is written down automatically - so the next developer isn't left guessing.

Comment

Inspiration

Every codebase has that one file nobody wants to touch. The commit says "fix bug". There's no issue, no discussion, no explanation. The person who wrote it left 18 months ago. You either leave it alone and work around it, or you change it and break something you didn't know existed.

Knowledge loss is one of the most expensive problems in software development. It slows onboarding, causes regressions, and makes codebases brittle over time. Every company has it. Nobody has solved it at the code level — until now.

What it does

When triggered on a Merge Request, the Institutional Memory Agent reads the diff, reasons about what changed and why, and posts a structured Decision Record as a comment on the MR. It also saves the full record to the repo under decision_records/.

Each Decision Record captures what changed in plain English, why this approach was chosen, what alternatives were considered and rejected, and what the next developer must know before touching that code again.

How I built it

Built entirely on the GitLab Duo Agent Platform using two YAML files. agent.yml defines the custom agent, its system prompt, and toolset. flow.yml defines the trigger flow that activates on MR mentions. Anthropic Claude powers the reasoning — analyzing diffs and writing documentation that captures the "why" behind every decision.

Challenges I ran into

The flow runs inside GitLab's CI sandbox where get_project returns a different project ID than the actual project. This caused consistent 404 errors across multiple versions. The fix was hardcoding the real project ID in the system prompt and removing the get_project dependency entirely.

Platform config caching was another issue — the platform kept running stale flow versions despite new commits, requiring careful version tagging and catalog mapping updates to force re-syncs.

Accomplishments that I am proud of

The agent works end to end and generates genuinely useful Decision Records. Zero configuration required for end users — just mention the agent on any MR. The records are detailed enough that a developer who has never seen the codebase would understand not just what changed, but why.

What I learned

How the GitLab Duo Agent Platform's flow execution environment works under the hood, the difference between agent.yml and flow.yml and how the platform syncs them, and how to design agent prompts that are resilient to sandboxed API limitations.

What's next for Institutional Memory Agent

Auto-trigger on merge without requiring a manual mention. A Wiki index page linking all Decision Records by component. Cross-MR linking so when a file is touched again, the previous Decision Record surfaces automatically.

Built With

  • claude
  • gitlab-duo-agent
  • rest-api
  • yaml
Share this project:

Updates