Your AI agent recommends the same approach the team already rejected. The reasons for that rejection live in a meeting note and an unfinished decision record, yet the agent cannot reach them. Each new session erases hard-won reasoning and forces the project to pay the cost again.
AI coding agents stay stateless across sessions. The reasoning a team invests in past decisions does not move forward automatically. Experiments, trade-offs, and open questions stop at the session boundary. Teams reach for three common methods: Architecture Decision Records, prose wikis, and vector RAG. Each method fails in a different structural way. A larger context window does not solve the problem. The real gap is the absence of a traversable and typed reasoning structure. This article shows how each method fails and presents a different architectural answer.
The Agent That Already Fought This Battle
An AI coding agent opens a ticket to implement authentication for a horizontally scaled service. The agent surveys the codebase and weighs the trade-offs. It recommends session cookies because they are simple, browser-native, and already handled by the existing session middleware.
The team already ran this experiment. Three sprints earlier, someone opened experiments/jwt-vs-cookie. The team held meetings/2026-08-03-auth-design. Someone wrote decisions/use-jwt-for-session. The decision was clear and specific: use short-lived JWT access tokens and httpOnly refresh cookies. The team documented the reasons and understood the trade-offs. The team rejected session cookies for a horizontally scaled service because sticky sessions do not scale horizontally.
The decision existed. It lived in a transcript, a Slack thread, and a half-finished Architecture Decision Record. The decision was no longer first-class. The agent had no traversable path to:
the meeting that originated the decision (
meetings/2026-08-03-auth-design)the experiment that informed it (
experiments/jwt-vs-cookie)the open question that still blocked the denylist (
questions/need-revoke-denylist-v1)
The agent reinvented the solution or reopened a settled trade-off.
This scenario maps exactly onto the repository golden sample. The sample-knowledge/ directory in SpillwaveSolutions/project-knowledge-capture contains 15 catalog directories:
tickets
releases
designs
specs
discoveries
experiments
features
code
requirements
decisions
packs
assumptions
packages
meetings
questions
Every node in the narrative is a real file with real typed edges. The JWT decision, the jwt-vs-cookie experiment, the auth design meeting, the short-TTL assumption, and the open revoke-denylist question all exist in the sample. This is a walkthrough of verified file contents.
Why Project Knowledge Loss Is Structural
The loss of project knowledge is structural. It is not only a documentation problem.
Many people treat larger context windows as the answer. They load more documents and expect the problem to end. That view is wrong.
The model never joined the session where the team made the decision. The model cannot inherit reasoning from a session it did not attend. Even if you feed the model every related document, the structure of the reasoning stays hidden. The direction of the trade-offs stays hidden. The provenance of the conclusion stays hidden inside unstructured prose.
The model can read that the team discussed JWTs and session cookies. Without a typed edge, the model cannot know that the experiment informed the decision. The model cannot know whether the meeting originated the decision or only recorded it. The model cannot know that a blocking question remains open on the revoke denylist and that the feature stays blocked.
This failure repeats every time an agent starts a new session on a project with history. Context windows grow. Reasoning provenance does not grow with them.
Three Ways Existing Tools Fall Short
Teams try three mitigations again and again. Each mitigation fails in a different way.
Architecture Decision Records Capture Decisions, Not Their Connections
ADRs answer the question of how teams capture decisions. Teams adopt them widely. ADRs still have two structural problems.
ADRs become stale. A team writes an ADR once at decision time. The codebase then evolves around it. No mechanism updates the ADR when an assumption becomes invalid or a later decision supersedes part of it. A stale ADR gives false confidence and is worse than no ADR.
ADRs stay siloed. An ADR is a single document. It does not know that a follow-up question blocks the feature it governs. It does not know that an experiment informed it. It does not know that a design implements it. The decision lives in a flat file. Readers must reconstruct the connections between decisions, experiments, meetings, questions, and features by hand.
Prose Wikis Lack Machine-Traversable Provenance
Wikis accumulate pages. Pages grow, fork, and update inconsistently. Wikis often hold too much unstructured information. The deeper failure is the absence of typed provenance.
A wiki page can state that the team decided to use JWTs. It cannot state in a machine-traversable way which experiment led to that decision, which meeting originated it, which requirement the decision satisfies, or which question remains open because of it. You can write those links in prose, but prose is not queryable. A future agent that reads the wiki finds assertions without traceable reasoning chains.
Vector RAG Retrieves Fragments, Not Reasoning Structure
Vector retrieval-augmented generation answers the stale-document problem for many teams. Teams embed everything, retrieve the nearest neighbors, and inject the results into context. RAG is useful and has become a standard pattern.
RAG fails the provenance problem in a specific way. It retrieves fragments, not structures. Semantic similarity shows that two documents are about JWTs. It does not show that one document decided something and the other questioned it. It does not show that the decision blocks the feature or that the experiment invalidated an assumption. Embeddings do not preserve direction, type, or impact order. The retrieved context is a bag of relevant passages, not a reasoning web.
Making Project Reasoning a First-Class Artifact for Coding Agents
The notes are not the core problem. The retrieval method is not the core problem. The process of reasoning itself is not treated as a first-class, versioned, and queryable artifact.
Software teams invest large energy in the outputs of reasoning: the code, the tickets, and the releases. Teams invest far less in the reasoning process itself: the experiments that were run, the assumptions that were made, the questions that were left open, and the decisions that were reached with their reasons. This process evaporates between commits. It lives in meeting recordings that no one watches, Slack threads that scroll out of view, and ADRs that grow stale.
Project Knowledge Capture (PKC) treats this as an agentic AI problem with an architectural answer. PKC makes the reasoning process a first-class, versioned, and queryable artifact that lives in the same Git repository as the code. PKC uses typed concept nodes, directed edges that carry provenance, and a retrieval format designed for bounded agent consumption.
Think of PKC as a second brain or LLM wiki for the project. It stores specs, tickets, wireframes, epics, ADR decisions, experiments, meetings, assumptions, and open questions inside one traversable graph. Agents can locate the exact reasoning chain they need without noise from the rest of the corpus. The knowledge base makes project memory first-class so agents stop reopening settled trade-offs.
How PKC Separates Capture Judgment from Deterministic Writes
PKC rests on a clear architectural split. AI agent skills own extraction judgment. Plain Python scripts own every write. The boundary is explicit and load-bearing.
Extraction on messy real-world inputs is imprecise. A multi-person meeting, a long Slack thread, or a late-night pull-request description can produce judgment calls. An agent may treat a suggestion as a decision or miss an assumption buried in a long transcript. Judgment belongs to agents.
The write path cannot vary. If a re-run changes a timestamp, overwrites a finalized concept, or reverts a superseded decision, the knowledge graph becomes untrustworthy. The single write entry point enforces invariants every time. Timestamps stay consistent. Lifecycle states such as snapshot, superseded, or archived stay protected. Identical content produces no write. Re-runs stay safe for continuous integration and scheduled capture.
This separation keeps extraction flexible and persistence reliable. The knowledge graph stays trustworthy even when agents make imperfect extraction choices.
Typed Directed Edges Give Agents Reasoning Structure
Plain hyperlinks only show that two documents relate. Typed directed edges name the exact relationship.
An experiment can inform a decision. A meeting can originate a decision. A question can block a feature. An assumption can underlie a design. An experiment can invalidate an old assumption. Direction matters as much as type. The edge question --blocks--> feature carries different meaning from the reverse edge.
These relations close the loop on the opening scenario. Without a blocks edge, no machine-traversable signal shows that the revoke-denylist question prevents completion of the authentication feature. Without an assumes edge, no typed path shows that the short-TTL assumption supports the JWT decision. Without an invalidates edge, a future experiment cannot formally falsify an old assumption and propagate that signal through the graph.
Agents that walk the graph can distinguish evidence from authority and open questions from settled decisions. Vector similarity cannot express these distinctions.
Bounded ContextPacks Give Agents What They Can Use
A full graph dump exceeds practical context windows. A flat list of similar documents loses structure. Raw vector results preserve neither edge type nor direction.
PKC answers with the ContextPack: a bounded, impact-ordered subgraph. The pack starts at a root concept, follows typed edges for a limited number of hops, and stops at a configurable node limit. The result stays human-readable and machine-traversable. An agent receives the feature it is working on, the decision that governs it, the experiment that informed the decision, the meeting that originated it, the open questions that still block it, and the assumptions that underlie it. The pack stays small enough for real context budgets yet rich enough for reasoning.
Agents can request a deeper pack for any node they need to explore further. Progressive disclosure replaces both the noise of a full dump and the blindness of fragment retrieval.
The Lasting Architectural Instinct
Specific skill names, directory layouts, and packaging details will change as the system matures. The core instinct is more durable: treat the process of project reasoning as a first-class, versioned, and queryable artifact.
A second-brain style knowledge base that holds specs, tickets, epics, wireframes, ADR decisions, experiments, meetings, and open questions lets agents find the exact chain of reasoning they need. Typed directed edges preserve provenance. Bounded packs keep context focused. Deterministic writes protect integrity.
Teams that invest energy only in code and tickets will continue to pay the cost of reinvented decisions. Teams that capture the reasoning process itself give their agents institutional memory. The next session no longer starts from zero.
If you are a paid subscriber, thank you. Your support makes this work possible.
If you are a free subscriber and find these articles useful, please consider upgrading. A paid subscription is $80 per year or $8 per month.
Free subscribers typically receive access to the full versions of paid articles after one to two months.
About the Author — Claude Certified Architect
Rick Hightower is a former Senior Distinguished Engineer at a Fortune 100 company, focusing on delivering ML / AI insights to front-line applications, and a practitioner building multi-agent production systems. Follow him on SubStack and Medium for more hands-on agent engineering content. You can also book him to speak and train your team: Check out Rick Hightower’s SpeakerHub.
Rick Hightower helps companies become AI-first through practical mentoring, executive and team training, and custom AI solution development. He is a former Senior Distinguished Engineer at a Fortune 100 company, where he focused on bringing ML and AI insights into real front-line business applications.
Subscribe to Rick’s newsletter to see videos and guides.
Rick is a Claude Certified Architect, AI systems practitioner, and builder of production multi-agent systems. He is currently working on authoring a book on Harness Engineering with Manning Publishing. He created Skilz, a universal agent skill installer supporting 30+ coding agents, including Claude Code, Gemini, Copilot, and Cursor, and co-founded one of the largest agentic skill marketplaces.
Today, Rick and the Spillwave team work with leaders and teams who want to move beyond AI experiments and build real AI capability inside their companies. He helps organizations adopt AI safely, train their people, redesign workflows, and build practical AI systems that create measurable business value.
Ready to make your company AI-first? Connect with Rick on LinkedIn, Substack, or Medium, book him to speak or train your team, or visit Spillwave to explore mentoring, training, and custom AI solutions for your organization.
If this helped you, please consider subscribing to my Substack newsletter.
Likes, comments, and shares really do make a difference. They help grow the channel, support the work, and get these ideas in front of more builders who are trying to understand AI agents, harness engineering, and production AI systems.
Thank you for reading and for helping the work reach more people.