My Architect, part 1: giving an AI agent memory and a plan

This is the first post in a series about My Architect — a system where the project lives on between AI agent sessions. The human sees and edits the picture through a visual interface, the agent manages the same project through MCP. The series has seven parts; the plan is at the end of this post.

The problem: the agent is brilliant and has no memory

Claude Code solves in half an hour what would take a senior engineer a day. Then the session ends. The next morning the agent doesn't remember why you chose Postgres, which features got pushed to the second release, or where you left off at eight last night.

The context window is finite. A long conversation gets compressed, and the first things to fall out are precisely the two-week-old decisions everything rests on. You explain it all over again, the agent "changes its mind" about things already settled, and sometimes redoes what was working.

The usual remedies:

• CLAUDE.md and notes in the repository. Works while the file is short. By line one hundred it turns into a dump where linter rules sit next to fateful architectural decisions.
• Plans in markdown files. PLAN.md, ROADMAP.md, TODO.md — each lives its own life, contradicts its neighbors, and the agent decides on its own which one to treat as the truth.
• Jira or Linear. Built for people and processes. At best the agent gets API access without any structure it can comfortably read: no requirement inheritance, no concept of "pick the next task taking the release and tree depth into account."

The shared flaw of all three: there is no single place that is equally convenient for both the human and the agent.

The idea: one source of truth, two interfaces

My Architect stores the project as a hierarchy of nodes: Epic → Feature → Story → Task (there are SAFe and simplified schemes). Requirements, documents and diagrams attach to nodes. Under the hood it's plain YAML and Markdown files — no proprietary database, the data will outlive any tool.

On top of a single store sit two equal entry points.

For the human — a canvas: a WBS tree with automatic layout, a User Story Map with releases along the horizontal axis, drag-and-drop for re-parenting nodes, statuses shown in color. Drag a story into another release — the file changes.

For the agent — more than 30 MCP tools. A typical session looks like this:

get_project_context(pid)   → hierarchy, backlog, releases — in one call
get_next_task(pid)         → a task picked with release and tree depth in mind
start_task(pid, node-42)   → status in-progress, agent assigned
create_doc(...)            → the spec attached right to the node
complete_task(pid, node-42, summary)
                           → done, parent statuses recalculated,
                             the next task already in the response

The sync is live: the agent closes a task — the node on the canvas turns gray right during the session, no reload. A file watcher fired: the backend noticed the YAML change on disk and broadcast the event to the browser over WebSocket.

What the agent remembers between sessions

A new session doesn't start from a blank slate, but with a single call to get_project_context: the whole hierarchy, the backlog, releases, statistics. From there the agent knows exactly what's done, what's blocked and why, and what to pick up next.

Decisions are stored not in conversation text but as requirements of four types: functional (FR), non-functional (NFR), architectural (SAR) and constraints (CON). Requirements are inherited down the tree: an NFR "response under 200 ms" attached to an epic is visible from every nested task. An agent picking up a third-level task gets both its own requirements and everything that has accumulated on its ancestors.

The agent's memory is not the context window. It is the project structure it reads in one call at the start of every session.

Why MCP and not yet another integration

MCP is an open protocol, and My Architect was built around it from day one, not as an add-on. Any compatible agent plugs in: Claude Code, agents on the Anthropic SDK, whatever comes tomorrow. The configuration is five lines in .mcp.json.

The flip side of the same coin: both the UI and the MCP tools go through one backend and one domain logic. The agent can't break what the human sees — they physically share the same files and the same rules for changes.

A small thing that's worth a lot

The system won't let the agent name a node "Implement login" or "Fix bug in auth". Nodes are named as entities: "Login system", "Auth flow". A built-in linter rejects verbs, imperatives and acceptance-criteria wording right at the build_hierarchy stage.

It looks like nitpicking. But after a month of work a backlog of two hundred nodes reads like a map of the product, not like a log of assignments — to both the human and the agent.

All parts of the series

1. Giving an AI agent memory and a plan — this post.
2. An architecture with no database — YAML files as the source of truth, atomic writes, a per-project mutex and live sync over WebSocket. Plus the story of how concurrent writes lost 85% of changes.
3. The planning model — hierarchy, requirements with inheritance, the User Story Map and releases: how to make the agent plan like an architect, not like a todo generator.
4. The agent's working loop — from get_next_task to complete_task: documentation as part of the task, the living source of truth and reconciling the plan against the real code.
5. Distribution through the Claude Code marketplace — a plugin that installs both the skill and the MCP server with one command: how the marketplace works, versioning, and why the skill lives in a public repository.
6. The human side — WBS, Building Blocks and the User Story Map — how an architect uses the tool by hand: WBS over building blocks, a User Story Map for prioritization, and a diagram the agent executes.
7. Obsidian, Claude Code docs and OpenClaw — field notes — what job other knowledge tools actually do, where each hits its ceiling, and why running a project with an agent is a different job.

You can try My Architect at my-architect.app. Questions and objections — write to me; I'll dig into the most interesting ones separately.