Durable AI-Agent Memory in a Homelab Repo with MCP Setup/Check Scripts

AI agents are stateless by default. Every time you start a new session, your coding assistant forgets every architectural decision, naming convention, and hard-won debugging insight from the last one. In a homelab repo where multiple agents (Claude, Codex, Gemini) touch the same codebase, that amnesia compounds fast. You need a durable memory layer with clear rules about what gets stored, how it is scoped, and what never goes in.

TL;DR

This repo now uses global Docker MCP gateway (MCP_DOCKER) instead of repo-local MCP server config files.
scripts/mcp-setup and scripts/mcp-check enforce that repo-local MCP files are absent and global MCP_DOCKER is present.
Memory persistence is handled by Docker MCP memory server state, while repo isolation is enforced by naming (Repo:subdepthtech.com ...).
The contract in .agents/agents/AGENTS.md is the source of truth for safe memory usage and prefix rules.

MCP (Model Context Protocol) is a standard for connecting AI agents to external tools and data sources through a unified server interface. In this context, the MCP memory server gives agents a structured way to read and write persistent context — decisions, assumptions, and session summaries — that survives across sessions and works across different AI clients. For a full introduction to the protocol, see our post on MCP explained for AI practitioners.

Evidence used

This post is grounded in:

scripts/mcp-setup
scripts/mcp-check
.agents/agents/AGENTS.md
README.md
CLAUDE.md
.gitignore

The contract: memory is operational, not optional

The contract in .agents/agents/AGENTS.md is explicit:

Start of task: query memory for repo/component context.
During task: record key assumptions and decisions.
End of task: write a session summary.

It also explicitly bans secrets and PII from memory storage. That policy is the part many teams skip.

How persistence is wired

At runtime, this repo relies on global MCP configuration:

Codex CLI global config defines MCP_DOCKER (docker mcp gateway run)
Gemini global config defines MCP_DOCKER (docker mcp gateway run)
Repo-local MCP files are intentionally not used in this repository

In the Docker MCP catalog, the memory server is backed by Docker-managed state. Operationally, that means persistence comes from Docker MCP runtime/storage, not from a repo-bound MEMORY_FILE_PATH.

Setup + validation workflow

Initialize/verify local contract and tooling:

./scripts/mcp-setup

Then validate:

./scripts/mcp-check

What mcp-check verifies:

repo-local MCP config files do not exist (.mcp.json, .codex/config.toml, .gemini/settings.json)
global MCP_DOCKER is configured
codex mcp list includes MCP_DOCKER and excludes standalone local memory
canonical contract exists and includes Repo:subdepthtech.com scope rules
memory artifacts are gitignored

Why this pattern is practical

It removes per-repo MCP drift. With one global gateway, you avoid hand-maintaining three local client config files in every repo.
It keeps one contract across multiple clients. .agents/agents/AGENTS.md defines one shared policy and prefix system for Claude, Codex, and Gemini.
It still supports repo-level isolation. Prefix scoping (Repo:subdepthtech.com) keeps memory queries and writes scoped by convention.
It remains security-aware by default. Memory instructions explicitly prohibit credentials and PII.

If you are using AI agents in your own repos, think about what happens when you switch between sessions or clients. Are your agents rediscovering the same context every time? That repeated work is a signal that you need a persistence layer.

Lessons learned

Validation matters as much as configuration. mcp-check catches mismatch between intent and runtime.
One global gateway plus repo naming discipline is usually simpler than per-repo server config.
Memory safety is a policy problem first; tooling enforces policy, it does not replace it.
Reducing moving parts improves repeatability in multi-agent workflows.

What I’d do differently

Add a CI check that fails if repo-local MCP files are reintroduced.
Add machine-readable output to mcp-check so external tooling can gate on specific failures.
Enforce Repo: prefix usage with a lightweight policy check before memory writes.
Add optional secret-pattern linting around memory write operations.
Document fallback steps when Docker MCP gateway is unavailable.

Security notes

Treat memory as sensitive operational metadata even without explicit credentials.
Follow .agents/agents/AGENTS.md: never store secrets, tokens, credentials, private keys, or PII.
Keep .agents/mcp/memory/ and *.jsonl gitignored to reduce accidental commits.
Scope all memory reads/writes to Repo:subdepthtech.com to reduce cross-repo contamination.
If multiple agents write concurrently, use append discipline and operational checks to avoid corruption.

Summary

A global MCP gateway (MCP_DOCKER) eliminates per-repo MCP config drift and works across Claude, Codex, and Gemini.
The contract in AGENTS.md is the source of truth: agents must read memory at session start, record decisions during work, and write a summary at session end.
Repo-level isolation comes from prefix scoping (Repo:subdepthtech.com), not from separate server instances.
Memory safety is a policy problem first. Explicitly banning secrets and PII from memory storage is the rule most teams skip and the one that matters most.
Validation scripts (mcp-setup and mcp-check) catch configuration mismatch between intent and runtime before it causes agent behavior drift.

How Are You Handling Agent Memory?

If you are working with AI coding agents across multiple repos or clients, I would like to hear your approach to persistent context. Are you using MCP memory, custom tooling, or just living with the amnesia? What rules have you found essential for keeping sensitive data out of agent memory? Share your setup or questions — this is a space where everyone is still figuring out best practices.