Building Project Pilot: Giving AI Autonomous Memory and Orientation

I’ve been building software with Claude Code for a while now. It’s genuinely impressive: fast, capable, and willing to tackle almost anything. But after a few weeks on a real project, I noticed: Claude Code is like a brilliant assistant that showing fresh every morning, but forget everything the next day.

That frustration turned into a project. This is how I built Project Pilot, a system that gives Claude Code the persistent memory, awareness, and judgment it’s missing, and does it entirely on its own, without requiring any extra effort from the developer.

The Problem No One Was Solving

It started with three things that kept going wrong.

Drift. I’d start a work session with a clear direction, and by the end of it, the AI had made a dozen small decisions I never saw, naming things in a certain way, structuring data, handling errors, that individually seemed fine but collectively created inconsistency. Over time, the project stopped feeling coherent, and I couldn’t explain why.

Amnesia. I’d make an important technical decision in one session, say, choosing a specific approach to user authentication. Three sessions later, the AI would contradict that decision without knowing. Not because it was wrong, but because the decision simply wasn’t in its memory anymore. It was gone.

Cascade blindness. The AI would confidently update one piece of code, and its own tests would pass. But a subtle agreement that another part of the system depended on, how errors were reported, or what format data came back in, had quietly changed. Nothing broke immediately. Everything broke eventually.

The most common approaches were self-updating Claude.md files (becoming big really fast and Claude code ignores half of it), static instruction files (quickly outdated), rules folders (required constant manual maintenance), and elaborate custom integrations (powerful but heavy to set up). None of them solved the core problem: keeping project knowledge alive and current without requiring the developer to constantly maintain it.

I wanted something that worked autonomously, no dashboards to check, no reports to read, no extra commands to run. Just build. The system handles the rest.

The First Decision

Before writing any code, I had to decide how this thing would actually work. There were two realistic paths.

Option A was building an MCP, a background program running alongside the AI that maintained a live knowledge database. This is powerful, but it also means installing extra software, managing a running program, and handling failures of a separate system. For a solo developer, that’s a lot of infrastructure to trust.

Option B was using Claude Code’s built-in automation triggers, called hooks, that fire automatically when the AI edits a file, finishes a task, or starts a new session. No server. No database. Just files and scripts, running in the same environment the AI already uses. The project’s knowledge would live as plain text files in a folder called .pilot/, stored alongside the code itself.

I went with Option B. The reasoning was: the system needed to be zero-maintenance by design. If it required a running server, it would eventually fail when I forgot to start it, when something conflicted, or when something crashed silently. Files and scripts don’t crash. They’re there or they’re not.

Everything was built upon this decision and it was easy to debug, easy to make changes, and easy to prove that the concept really works.

Designing the Brain

The knowledge layer needed structure. Not just “dump everything into one file”, that creates the same problem as no memory, just with extra scrolling.

I settled on a layered system. At the foundation sits a project brief that captures what the project is, who it’s for, and, critically, what’s explicitly out of scope. Above that, an architecture file records every significant technical decision with its reasoning, what alternatives were considered, and the conditions under which it should be revisited. A patterns file codifies the conventions the AI should follow. A decisions log tracks the full lifecycle of choices, active, replaced, or abandoned.

The key insight was the decision lifecycle. Most systems treat decisions as permanent. But in practice, decisions evolve. You choose one approach to authentication, and six months later your requirements change and that decision deserves revisiting. Project Pilot tracks “Revisit When” conditions on every decision and periodically checks whether those conditions have been met.

Two internal files do the real-time work. A change log records every file the AI touches, every command it runs. And a critical paths list maps sensitive areas of the codebase to rules, so when the AI edits anything in the authentication folder, it immediately sees a warning about what must never be broken there.

Where Things Went Wrong

The first complete build looked great in theory. Then I tested it.

Bug #1: The wall of text. The end-of-session script, the one that fires when the AI finishes working and needs to update the knowledge files, was dumping its entire instruction set directly into the visible conversation. Every few prompts, the developer would see 40+ lines of internal instructions scroll past. Completely unusable.

The fix was to move the detailed instructions into a file the AI reads silently, and have the script output only a single summary line: “Session 11 complete: 3 changes logged”. The developer should know that the system was updating itself, but 40+ lines of code at the end of each work aren’t helpful.

Bug #2: Windows compatibility. The scripts used a way of reading system settings that only works on Mac and Linux. On Windows, which I was using, they simply didn’t work.

The fix was to rewrite scripts using Node.js, eliminating the platform-specific commands entirely.

Bug #3: The infinite loop. When the AI finishes a task, an end-of-session trigger fires and tells it to update the knowledge files. The AI updates them, then finishes again. The trigger fires again. The AI updates again. Forever.

The fix was a simple guard: the trigger checks whether it’s already running before doing anything. If it is, it exits cleanly.

Bug #4: Lost work on memory compression. Claude Code has a command that compresses the conversation history to free up space when sessions get long. The problem: compressing doesn’t trigger the end-of-session update. Any unsaved knowledge from that session just vanishes.

The fix required two triggers working together. One fires before compression and flags that unsaved changes exist. When the session restarts after compression, another trigger detects the gap and tells the AI to catch up before doing anything else.

In total, I found and fixed twelve bugs before the system was stable. Every single one was discovered through testing, not through thinking. The lesson was clear: systems that interact with real-time AI behavior are impossible to get right by reasoning alone.

The Distribution Problem

With the system working, I faced a new question: how do people actually install this?

My first approach was a ZIP file with automated install scripts. This worked but felt fragile, users had to extract files to the right places, trust a script to modify their settings, and remember to restart the AI. Too many steps, too many things to go wrong.

My focus was on the native plugin system in Claude Code, a marketplace where tools install with a single command, hooks are declared in a standard configuration file, and commands get automatically organized under the plugin’s name. No install scripts. No manual file copying.

Converting to a plugin meant a small restructuring. The marketplace has specific requirements about how files must be organized. Somehow Claude isn’t really sure about the rules for a marketplace, but a little bit of a manual search fixed the problem. None of it was glamorous work, but the result was a dramatically better installation experience.

What Project Pilot Actually Does

The final system has five automatic triggers that work together invisibly.

When you start a session, the startup trigger checks how long you’ve been away. If it’s been weeks, it suggests a guided walkthrough to get reoriented. If there are unsaved updates from a previous session that was compressed or interrupted, it triggers recovery first. If detailed context files exist for specific parts of the project, it makes sure the AI knows where to find them.

While you work, an edit tracker fires after every file the AI touches. It logs the change and checks whether the file falls under any protected areas. If you’re editing authentication code and you’ve flagged it as critical with the rule “all routes must check user credentials,” the AI sees that warning immediately, while it’s working, not hours later.

When the AI finishes and stops, a session synthesis runs. It counts how many changes happened and assigns a weight: light (1–5 changes), medium (6–15), or heavy (16+). Light sessions update the current context and progress log. Medium sessions also scan for emerging patterns in the code. Heavy sessions check whether any decision’s “Revisit When” conditions have been triggered, and assess whether the project has grown in ways that require restructuring the knowledge system itself. Every fifth session forces a deep review regardless of change count.

Before memory compression, a pre-compression snapshot records how much unsaved context exists so nothing is permanently lost.

The onboarding experience is a guided conversation, not a form. The system scans the project automatically, detects the technology stack and existing conventions, assesses complexity, and asks focused questions. For simple projects, a few questions and you’re done. For larger ones, it walks through technical decisions, naming conventions, security rules, and scope boundaries. Every answer feeds directly into the knowledge files. No placeholders. No generic text.

How to Install It

If you’re using Claude Code, installation is two commands:

/plugin marketplace add David-Mazig/Project-Pilot
/plugin install project-pilot@project-pilot

Restart Claude Code, then run /project-pilot:init-pilot and answer the onboarding questions. That’s it.

From that point on, the system maintains itself. You’ll see a short one-line message occasionally, a synthesis notification, a critical path warning, and nothing else. The knowledge files are always current, always version-controlled alongside your code, always available to the AI at the start of every session.

You can read everything here: https://github.com/David-Mazig/Project-Pilot

What I Learned

The biggest lesson wasn’t technical. It was that the hardest part of building a Claude code developer tool is making it disappear. Every feature that required the developer to do something, check a dashboard, read a report, run a command, was a feature that would eventually be ignored. The only features that survive in the long run are the ones that work without being noticed.

The second lesson was about testing AI-integrated systems. Standard software testing assumes that if you give the same input, you get the same output. But a system that interacts with an AI’s decision-making introduces unpredictability at every step. The only way to validate it is to simulate complete real-world scenarios, startup, work session, critical path warnings, end-of-session updates, memory compression, recovery, and verify that the entire chain produces sensible results. I ended up writing 75 tests across 10 phases. Every bug I found after the first version surprised me.

The third lesson was about scope. I originally envisioned semantic search, a live knowledge graph, confidence scoring, and a full background server architecture. What shipped was plain text files and five small scripts. And it works better than the ambitious version ever would have, because it’s simple enough to be reliable.

If you’ve been building with an AI coding tool and felt that creeping sense that your project is slowly losing coherence, decisions being unmade, context forgotten, changes cascading in ways you can’t track, that’s the problem Project Pilot exists to solve. Not by giving you more to manage, but by managing it for you.

The plugin is open source. Install it, answer a few questions, and forget about it. That’s the whole point.

So what’s next… Smarter context window management.