What should PAAD remember?

[Ovid]

PAAD needs memory. Memory is a trap.

Code doesn't capture everything a project knows: intentions, unfinished work, recurring friction, decisions whose rationale evaporates after the branch merges. PAAD needs memory.

But many agents are already experimenting with persisting memory and they can remember the wrong thing. The hard problem isn't storage. It's what to remember, when to surface it, how much authority it has, and how to know when it stops being valid.

Worse, PAAD has to do so in an agnostic way.

Key question: is this a problem worth solving, given that many AI coding tools are independently trying to solve this? I find that they don't solve it very well and that Claude Code often fails to consult appropriate memory.

Memory is drift

A spec can drift from code, but at least you can compare them. Some memories have no source of truth at all. "We use X because Y lacks Z" may no longer be true.

Where memory has a source of truth, point to it and revalidate it. Where it doesn't, record what makes it valid.

Memory becomes authority

This worries me more. Steering files shape agent behavior, so a recorded decision becomes an instruction. "Don't use Redis because condition X applies" can survive after X disappears, and the AI rejects Redis forever.

Three variants:

1. phantom (nobody decided it; the AI inferred it)
2. expired (the rationale no longer holds)
3. overbroad (right in one scope, applied everywhere).

Two rules follow:

1. Memory is evidence, not truth.
2. The authority of a memory must never exceed the authority of its source.

An untrusted webpage must not become project policy just because the AI wrote it into memory.

Four kinds, four lifecycles

1. Intentions (human-owned, human-pruned)
2. handoffs (temporary, aggressively replaced)
3. friction (auto-captured, most likely to become garbage)
4. rationale (lightweight ADRs, superseded rather than edited).

Every active memory needs a validity model: until PR #123 lands, while dependency X lacks feature Y, until superseded. Check it automatically where possible. Invalid memory isn't deleted; it stops being active:

proposed → active → superseded/revoked

Evidence reopens decisions. Preference doesn't.

If the AI can relitigate every decision whenever it prefers another design, memory fails in the opposite direction. New evidence earns /rethink: a revisit condition fires, supporting evidence stops validating, or recorded friction accumulates against a decision.

Keep it boring

Retrieval starts cheap with what PAAD already knows: current files, branch, task, recorded scope. Raw local observations (which may contain security findings) stay out of the repo; reviewed team knowledge gets committed.

@KennySmash's draft PR #11 appears to get write authority right: sub-agents record observations and handoffs; confirmed decisions stay under lead/human authority. However, it can "seal" decisions. Sealing proves a record hasn't changed, not that its assumptions remain true. Integrity isn't validity.

By Kenny's own comments, it's a PR for discussion, not merging. I also think that it's huge (that might be OK) and there's possibly a cleaner way forward.

Open questions

1. What threshold of contrary evidence earns /rethink?
2. What gets promoted from friction into memory without building a trash heap?
3. How should cheap relevance work?
4. Which decisions are so important that failing to retrieve them is unacceptable?
5. What should PAAD refuse to remember at all?

If this survives discussion, it may become a PAAD skill. If it doesn't, that's great. Bad solutions are worse than no solutions.

[Ovid]

Also worth noting that if you install PAAD globally instead of per-project, that might change the shape (and power!) of solutions.

[KennySmash]

Some great questions, with some of my later and larger projects I have been following a pattern of having the developer harness separate to the code base as that lets us break out the core application code prior to deploy and the harness is where the memory lives, I personally am running PAAD installed globally and it seems to do a good job of keeping things scoped to the harness

for relevance I'm trialling a tool called Graphify and its been doing ok with my test run Godot codebase

as for the importance of memory, I think having a tiered approach tied to the creation and a bit of business logic works, the main application I work on has a few tiers of importance to the decision as we and agents need to know if this memory formed from hard business logic example being a process that needs to support an ISO standard or other industry must-have or it could be a decision based on what the current architecture of our server hosts support like "we work in XYZ way due to limited VLAN support" and having this baked into the memory gives us greater context to allow rethinks later so if we run an agentic audit prior to moving infra then that clues the agents in that all memories tagged with infra are open to exploration/refinement

my personal ideal here is to provide some mechanism that allows me to quickly answer questions from internal audit about why something is done that way and what evidence do we have that its the right decision in the context of the business

perhaps an addition to the memory would be an explicit validity condition rather than leaving it to interpretation or inference

[Ovid]

perhaps an addition to the memory would be an explicit validity condition rather than leaving it to interpretation or inference

I'm looking at TEPA: Revoking Stale Memories for Conflict-Robust Language Agents to get ideas of how to proceed. I'm still stuck on the question of whether I should proceed. PAAD is growing larger than I expected and sprawl is not something anyone really wants.

[KennySmash]

maybe a sibling project then with just a mention? since its a larger problem that has a crowd already, it might be good to have something that's first party and talk each others language

[wphillipmoore]

The MEMORY.md mechanism in Claude Code is NOT the solution here. I've watched Anthropic evolve this feature over 2026, and I do NOT like it. Why? Where do I begin....

First, and to be fair to Anthropic, I haven't looked at how things have changed get in a month or two (since implementing the controls I am about to describe), but the feature doesn't appear to have been very well thought out. There was, at one point, a limit on how much of the memory the agents would bother to read, yet they were NOT limited to how much they could WRITE to that file, making changes after a certain point silently meaningless.

Second, the agents decide what to write, and they ALWAYS do so in the current project's MEMORY.md. This created a problem that haunted me for a couple of weeks: I am using a common set of tooling to manage a LOT of distinct git repos. Changes to the memory for ONE, do not impact the agent behavior of any others. After I fixed a bug that had been annoying me for a while, I would still manifest itself in TWEO of my N repos. Why? The agents had written a workaround for the bug into the memory for those two repos (without my knowledge -- I missed the brief mention of it). Once the bug was fixed, the workaround started to break... Finding THAT took me well over a day of debugging.

That was also the day I learned about the existence of MEMORY.md, so I went and audited the files, and holy shit.... EVERY SINGLE REPO had 20-30 entries, each of which had a non-trivial impact one how the agents behave, sometimes in VERY significant ways. Forcing Claude to stop writing to these files was not easy. In my typical fashion, I've gone overboard on this:

[-] My global CLAUDE.pm has explicit instructions to seek APPROVAL for all memory updates. That gives me a chance to redirect them.
[-] /memory-init skill (which I am not always remembering to run) -- this bootstraps MEMORY.md with similar warnings
[-] /memory-audit skill -- to review and purge or centralize each repo's bespoke entries (and I need to schedule running this periodically -- the sprawl is real)

OK, so how am I addressing this? I have 6 major projects I'm working on in parallel (each represented by a git organization with multiple repos). Having used Jira for years, I decided to cobble together some tooling to aggressively leverage GitHub issues to manage my development work. I have some basic requirements, like a 1:1 relationship between an issue an the PR that closes it, plus some additional tooling to enforce and manage how issues are created and updated.

I am now using "Epics" (a GH issue with the epic label, respected by the tooling as a container for other issues) to manage everything I do. Every active worktree is associates with a GH issue (tooling requirement -- can't even create the corktree without one), and I use the comments in the issue to track the state of the work. The epic manages the inter-task dependencies, and each epic starts with a brainstorming/pushback/writing-plans/alignment iteration, that produces a single spec/plan for the epic, and expands the subissues into individual tasks that implement the plan.

This is NOT trivial, and it's somewhat mature, but the take away is that I am using GH issues, with my bespoke tooling (which in theory is OSS, but a part of my Vergil system -- the idea could be extracted, but not the code, easily). GH issues become that backing store for all of my project planning AND execution.

/epic-implement takes an epic GH issue #, and starts cranking... It is able to reconstruct the ENTIRE STATE of the work being done (which could very well span repositories -- the epic's are org-specific, not repo-specific, and yes, I have hacks to support cross-org issue management, but now IO am getting excited and digressing....).

OK, I'm not sure how this contribution helps move the discussion along, and GH issues are hardly a generic solution to this problem, but architecturally, I think the problem you;'ve stated is in many ways the problem space these issue management tools are well designed for. I've tried to bridge the gap between GH issues and all of my automation and tooling, and in practice it's working pretty well. Whether this is relevant or not depends I suppose on whether or not you have embraced issue management tooling as a part of your own infrastructure.

[wphillipmoore]

I read this again, and see I left out a link I was intending to make...

I manage a LOT of the same types of "memory", but map a lot of them (particularly handoffs and friction) into issue comments. The longer term ones (intentions and rationales) are embedded into the spec/plan documents, and those are allowed to be updated as the plan collides with reality.

I added a required last issue to my epic workflow: the retrospective, which is implemented as a skill. The agent and human review the work done, and chronicle what went right, what went wrong, etc. That is also my opportunity to direct the results of lessons learned and problems found into follow on work. I keep the epics open until I spend a few minutes on the retro, and it has in practice closed a lot of cracks and gaps that problems were falling through. That step produces a retrospective.md next to the spec.md/plan.md files.

I am finding that the 3 documents together end up telling the story of the lifecycle of the act of solving a problem and implementing a solution.

Now... If you can have the components of PAAD collect things that need to be saved as memories into a structure that groups them the way you have, then I can see a skill you run to process that collection, and route them appropriately. That is soft of what I was doing with /memory-audit, so perhaps building on the MEMORY.md concept but adding a layer of classification. and categorization to the things you don't want to forget. You'll handle each of them fairly differently, I think.

[KennySmash]

one of the big issues I ran into early on was bloated file size and the only worthwhile fix that I've had success with is breaking things down to a single file per issue and having the date and description as the file name.

Models seem to fixate on certain files per session if they read the contents in once so a part of the usefulness is the filing system as a tree list so it helps inform the availability of what I like to think of as tech context rather than memory

I think the semantics of what we call it in the skill will affect how the agents approach it given how various providers will fine-tune for their particular flavours of memory

[samvallad33]

The three variants you listed, phantom, expired, overbroad, are the clearest breakdown of this failure I have seen written down. Most memory tools only really guard against the first one.

Memory is evidence, not truth, matches what I ended up building around after getting burned by the same drift you describe. A recorded reason like we use X because Y lacks Z needs to point at something checkable, and when it cannot point at anything, that itself should be visible rather than silently trusted forever.

The part I would push on is surfacing. Even correct memories get overbroad the moment they cross scope, and the agent has no way to know it happened unless something forces a revisit. What worked for me was treating every memory as decaying by default, so anything nobody has touched in a long time gets flagged for a second look rather than sitting there as quiet authority. It does not solve phantom or overbroad on its own, but it stops old expired-but-forgotten memories from being the ones doing the most damage, since they are exactly the ones nobody revisits.

I would genuinely rather see PAAD solve this well than not attempt it, since as you say the existing tools mostly do not. If comparing notes on the surfacing and revalidation side is useful, happy to. Repo is https://github.com/samvallad33/vestige, been living in this exact problem for a while.