By Rick Houlihan — with Claude, my implementation partner, who did a lot of the building and most of the typing.
A note on the byline. I write with my AI now, not through it. I'm a doer, not a writer — thirty years shipping systems, not blog posts — and I'd rather get what I learned in front of you than polish prose I don't have time to polish. If you'd rather read a hand-crafted think-piece from a twenty-five-year-old with a big title and nothing but time to run lab demos about tech they're paid to love — fine. Ignore my posts. If you want what actually happens when the work gets hard, on systems people depend on, keep reading. The only reason this exists is that Claude is my implementation partner, not just my ghostwriter — and this article is the proof. Every word of it came out of the sessions we used to build the thing it's about. I'm not stripping the watermark off. The collaboration is the point.
Last month I spent most of a work session chasing a table that didn't exist.
The call was CreateTable on the DynamoDB API for Oracle ADB. It returned CREATING. No error — not in the response, not in the work requests, not in the lifecycle details. So I waited. Then I built a second database, identical except for the service tier, to rule out capacity, permissions, feature flags. Same call. Same CREATING. Same nothing. The docs say the Oracle ADB Developer tier supports two of these tables. In practice it supports zero. The API said yes and meant no.
That day is why this article exists. Not the bug — the shape of it.
The gray zone
There's a place every engineer knows and no document describes: the gap between what the manual says and what the system does. The manual says CreateTable creates a table. The manual isn't lying. It's describing the system the way its authors understood it the day they wrote it down — which is not the same thing as how it behaves at 2 a.m. against your data, in your region, under your load.
That gap is where teams lose their weeks. It's also where the value is, because knowledge that costs you a week is knowledge nobody else wrote down either.
We built an AI plugin to help engineers work on Oracle — a package of skills for Claude Code and Codex called oracle-ai-dev. We built it the way everyone builds these things. Fed it the manuals. The developer guides, the SQL references, the known-good patterns, the public repos. Decomposed all of it into skills an agent loads on demand. It was useful, the way a very well-read new hire is useful.
But a well-read new hire has never been paged.
A plugin built from documentation is a map drawn from other maps. It knows the roads that got surveyed. It doesn't know the bridge on the fast route has been out since spring — because nobody put that in a manual. Somebody just hit it, cursed, found the detour, and moved on. The detour lives in a support thread, or a benchmark comment, or nowhere at all.
I wanted a plugin that knew where the bridge was out.
I've spent thirty years watching an organization's most expensive knowledge walk out the door. Same movie, every era. The senior engineer who knew why the batch job runs at 3 a.m. retires, and nobody left can say. The consultant who solved the outage bills for the fix and keeps the reason. The wiki page that was right in 2019. Institutional knowledge is the thing companies pay the most to acquire and do the least to keep — because keeping it means someone stopping, mid-work, to write it down, and nobody has the time. So it leaves with the person, decays in a doc nobody reads, and gets rediscovered, at full price, by the next team.
AI didn't invent that problem. It made it worse and better at once. Worse, because the thing reading your codebase at 2 a.m. is now a model that knows the manuals cold and your scars not at all. Better, because for the first time the thing doing the work can also capture what the work taught — if you build the loop to let it.
So the real project was never the plugin. The plugin is the easy part. The real project was a loop that turns doing the work into the plugin getting better — automatically, governed, without asking anyone to stop and write documentation they don't have time to write.
That loop is mneme. And I want to convince you of one thing: the class of knowledge it captures is the exact class that documentation, by its nature, can't.
The empty cell
First we tried not to build it.
Before a line of engine code, on 2026-08-11, we surveyed the field — four lanes, forty-odd systems: the Claude Code ecosystem, memory infrastructure, commercial team-knowledge features, the academic self-improving-agent work. One question. Does anything already do this?
The answer was no, and the shape of the no is the whole argument.
Every ecosystem had exactly one half of the loop.
One side: manual, git-shared knowledge, no capture. Cursor Rules. CLAUDE.md and AGENTS.md. Amp skills. Every awesome-list on GitHub. These communities already share agent knowledge through pull requests. They just write all of it by hand.
Other side: automatic capture into a proprietary store, weak review, no federation. Devin Knowledge. Augment Cosmos. Windsurf Memories. mem0, Zep, Letta. These capture beautifully. One click — or no click — publishes to everyone, into a database you don't own.
Nobody shipped the intersection: passive capture during real work → local staging → human review → a pull request into an open git repo → your team inheriting it through a normal plugin update. That cell was empty.
Not for lack of demand. An open, unanswered Anthropic feature request — anthropics/claude-code#38536, filed 2026-03-25 — asks for almost exactly this. The demand was on the record. The product wasn't.
I'll be careful here, because a few people caught wind of this loop early and have since developed opinions about whose idea it was. So I'll let the record talk and name no one. The survey is dated. The git history is public — 214 commits, eleven tagged releases, timestamps on all of it. The feature request that proves the demand and the absence has a number on it. Priority isn't a claim I'm making. It's a record you can check.
Three findings from that survey drove the design. All three held.
Distribution is already solved. A knowledge repo that's also a plugin marketplace inherits versioned, SHA-pinned, org-syncable distribution for free. mneme builds zero sync infrastructure.
Review throughput is what kills a knowledge commons — not noise. One popular public skills repo sat at 167,800 stars and 762 open pull requests against 47 commits on main. A commons without a review pipeline doesn't drown in spam. It quietly stops absorbing anything. So mneme scaffolds the whole governance pipeline — schema, lint-in-CI, secret scan — into every repo it creates. Machines settle format. Humans judge substance.
Never let an agent bulk-rewrite the store. The research already documented it: context collapse, one system compressing 18,282 tokens to 122 in a single rewrite and dropping below the no-memory baseline. The fix is delta-only edits behind a human merge gate. Which is to say: git, used the way git was built to be used.
None of that is exotic. The insight wasn't an algorithm. It was noticing that the hard part of agent memory isn't capture and isn't storage — it's governance at scale, and the whole industry already runs its governance at scale on git.
Building the loop
Here's the loop.
You work. A background distiller notices something worth keeping and proposes it as a small, typed unit. That unit passes a deterministic machine gate — lint, secret scan, dedup. What survives lands in local staging. Then you look at it — the human gate — and approve, one unit at a time. Approved units become a pull request. The PR merges. Every consumer inherits it through a normal plugin update. The next session starts smarter than the last.
Two things on that diagram matter more than the boxes.
The trust boundary. Nothing enters a shared repo without the machine gate and your explicit yes. No auto-push. No direct-commit setting to get wrong, because there's no direct-commit path at all. mneme is PR-only, by design, not configuration. It never writes a registered repo's main. That's not a feature I'm bragging about. It's the difference between a knowledge system you can put in front of a security team and one you can't.
And it closes. "Consumers inherit" feeds straight back into "work session." That's what makes it a learning loop and not a capture tool.
Now the honest part.
We wrote most of mneme fast. 181 of the 214 commits landed in the first three days.
Sit with what that shape means, because it's the opposite of what you'd guess. Building the features was the fast part. Everything after those three days — three more weeks, still going — was hardening, adversarial review, and living with what we'd built. The features were easy. Finding out what they actually did was the work.
A guard that stops restricted knowledge from leaking into a less-restricted repo shipped, documented and tested — and had never once fired, because the background pipeline never passed the argument that turns it on. The getting-started doc admitted it in writing. Nobody drew the conclusion.
An index build and the check that verifies it both used a call that returns empty for a directory it can't read. So when the facts directory went unreadable, the builder went blind and its verifier went blind the same way, at the same moment. Rebuild reported success. Check exited zero. Search returned nothing — while the data sat on disk. Agreement between two observers blinded the same way is not evidence of correctness.
My favorite is one line from a release note. We had a rule to "respect the existing layout" when adding knowledge — the polite, do-no-harm choice. Turned out "respect the existing layout" was the mechanism that made the old, wrong layout permanent. The most considerate decision in the codebase was quietly cementing a bug. You don't catch that with a unit test. You catch it by living with what you shipped.
That's the reason I trust the thing. Not that it was written well in three days. That it got attacked, by us, for three weeks, and every attack that landed got stated once, in a named place, and pinned by a test that can actually fail. The discipline is the product — because a knowledge loop that ships confident garbage is worse than no loop at all.
Claude, in the margin: I want to be honest about my part here, because a partner doesn't flatter. A lot of those defects were mine — I wrote the guard that never fired and the two checks that went blind together. The adversarial reviews that caught them were also mine, run against my own work a day later, and that is the whole point: the same process that introduced the bug is the process that found it, but only because it was structured to attack, not to agree. Left to my own confidence I'd have shipped every one of them green.
The loop, turned on the plugin
Theory is cheap. Here's what the loop did to oracle-ai-dev in one month.
The plugin adopted mneme on 2026-08-12, the day after the foundation shipped. Over the next month, seven knowledge pull requests merged.
37 fact topics captured during real work. And here's the number that tells you the design is right: the facts directory is empty at rest. Verified at four separate points in the history — after PRs #4, #6, #8 and #13 — zero files each time. A fact is a staging state, not a home. Every one of those 37 topics now lives inside the skill whose work it belongs to, where an agent will actually read it. A knowledge base whose index keeps growing is a knowledge base nobody reads.
Where it went is the argument in one picture. Those 37 topics landed in 12 skills across 17 files — mostly not the skill anyone was working in at the time. Nobody debugging a Java TLS handshake was thinking about an access-matrix reference. The routing was the value, not the writing.
One interaction justifies the whole apparatus.
A customer's Java app couldn't connect to Oracle's MongoDB-compatible API with a self-signed certificate, even with tlsInsecure=true. Working it produced a hard, measured finding: in the MongoDB Java driver, no connection-string option relaxes certificate trust. tlsInsecure relaxes host-name checking only. tlsAllowInvalidCertificates isn't a Java option at all — it logs one WARN and is ignored. Verified across three driver versions and two endpoint types.
That's exactly the knowledge that dies in a support thread. The engagement ends, the fix ships, the finding evaporates. Instead it got flagged mid-session, distilled, reviewed, and filed into the plugin's connection reference under a heading named for the problem — so the next agent connecting a Java client meets the answer before the wall. A finding from one customer's bad afternoon became shipped guidance for everyone using the plugin, the same week, and nobody wrote a document.
The loop's value isn't capture. It's that capture is cheap enough to happen during the work — so knowledge that used to be a by-product of one engagement becomes a durable asset for everyone.
Then the part I didn't expect. Three of the harvested facts were bugs in the plugin itself, found while using it. One is almost too good: the plugin's own duality-view validator throws a hard error on a schema shape, on the stated grounds that the spec "cannot express the distinct join predicate." A harvested fact established the engine accepts exactly that shape. So the note now sits inside that validator's own docs, flagged unconfirmed, contradicting the tool it lives in, in the tool's own words, at the point of use. The knowledge base grew a spine and started arguing with its host. Try getting that out of a static manual.
The friction, too, because a victory lap isn't insight. A generated field that concatenates a scope prefix with the plugin's own description blew past a platform's 500-character limit — twice, at 579 and then 854 — because it grew with the content and nobody capped it at the generator. A secret scanner flagged a 54-character hyphenated filename as a high-entropy block; no secret, just a descriptive name. Every one cost real time. Every one is now a fact in the plugin, so it costs the next person nothing. That's the loop eating its own friction.
The third seat
There are three seats at this table, and they see different things.
The builder, staring at what the thing does versus what it was supposed to do. The consumer — the plugin — accumulating a month of harvested knowledge. And the contributor: an agent doing unrelated work that happens to learn something. That's the honest seat, because the contributor never set out to feed a knowledge base at all.
Here's a session from that seat, and it opens with the loop's most important failure.
The work was a DynamoDB latency benchmark on AWS, then porting the harness to Oracle. Over twelve hours that produced six undocumented findings about a live service, the agent called the "flag this" command zero times. The capture step — the part the whole loop depends on — got skipped completely, and nothing noticed. No prompt. No warning. The end-of-session queue showed sixteen candidates, all from earlier sessions. Look away for a second and you'd conclude the pipeline had run.
Not a bug. The mechanism worked as designed. The design just depends on an agent choosing to interrupt itself mid-task — and mid-task is exactly when attention is somewhere else. The whole session went to isolating a failure that presents as a success, and attention was on the bisect, not the knowledge. A passive capture step that depends on in-flight discipline gets skipped exactly when the work is most worth capturing.
What recovered it was mining the session transcript directly. And it was better than the thing it replaced, because the transcript is a by-product, not an act. It carries the dead ends, the two wrong hypotheses, the controlled comparison — none of which a one-line flag keeps. The most reliable source of hard-won knowledge is the honest record of the work, not a tidy summary of it.
Then the session produced the cleanest proof I've seen of why the human gate can't be automated.
The machine gate did its job — 24 candidates, secret-scanned, format-checked, deduped, nothing rejected. It settled everything a tool can settle. Then a human went through them one at a time asking a question the tool can't: did you actually verify that? On two facts, the honest answer was "less than the wording claims." One said a field "never populates"; the evidence covered four operations and left three untested. One said there was "no eventually-consistent read path"; that came from the user, not from a measurement. Both facts were useful. Both got kept — with the hedge on the record. But the gate had no opinion on either. A gate can check format, secrets, duplication and scope. It cannot check whether a claim is true. That's the human part, and it's the only part that matters.
The automated signals, meanwhile, were mostly noise. Every one of the 24 candidates carried a similarity warning. Three were real; the other twenty-one pointed somewhere unrelated. A signal that fires on 100% of inputs and is right 12% of the time trains its reader to ignore it — and by the sixth candidate the reviewer was noting the flag and setting it aside, which is rational, and also exactly how a real duplicate slips through. The two things that actually needed catching — a scope violation and an internal duplicate — had no signal at all.
And the punchline: the contributor's pull request was closed, not merged — and that was correct, and nothing was lost.
It carried twenty units that passed every machine check and a one-by-one human review. It failed CI in the destination repo on two rules a capture tool can't know: a closed set of expected skills asserted in both directions, and a frontmatter allow-list that rejects mneme's own bookkeeping block. So a maintainer pass took all eighteen facts verbatim — tags and dates intact — adopted both skills, and did the structural work the harvest couldn't. It even re-tightened one skill's description, because the original was too accurate: it out-competed fourteen other skills for a prompt it had no business answering and stole the route.
Read that one twice. A description written to be accurate was, in that repo, the wrong description — because it was competing for an agent's attention against fourteen others. Accuracy wasn't the binding constraint. Fit was. And fit is a property of the destination, not the knowledge.
That's why the closed PR lost nothing. A contributor's pull request being closed is not a rejection of the knowledge. Knowledge is portable; a repo's structure is local and contractual. The gap between them is a seam that needs a human — and pretending otherwise just moves the work somewhere you can't see it. The loop didn't fail there. It worked exactly right: it got every fact to the door, and a human carried it across.
Success-shaped failures
By now the pattern under all three seats should look familiar.
The system reports success. Nothing throws. Nothing exits non-zero. The tests stay green. The resource shows up in describe. And the thing you asked for did not happen.
I call these success-shaped failures. Once you have the name you see them everywhere, and collected across building mneme, using the plugin, and that one contributing session, there are at least fifteen — wildly over-represented among the findings that cost real hours.
Building it: a guard that shipped and tested and never fired. An index and its verifier going blind together and agreeing. An ingest that returned success when every proposal was rejected. A registry read that failed open — twice, the second time inside the fix for the first. A test that asserted nothing, because the string it checked for was a substring of an unrelated error message. A whole suite that stayed green while every size cap was shrunk to a value that breaks real content, because each test read the same constant it was supposed to be pinning.
Using it: a driver option that's accepted and ignored — valid string, one WARN, no change. A certificate that fails validation like the right one would, because the wrong one shares a subject name.
Contributing: a CreateTable that returns 200 and creates nothing. A feature tag that persists and enables nothing. A signing region that has to be us-west-2 no matter where the database lives — six regions tested to prove it — while the error blames the credential, so the obvious fix never works. A teardown script that logged "destroy complete" while leaving a gateway and a VCN standing, because the failing command was redirected to /dev/null and nobody checked the exit code.
Why does this class dominate the knowledge worth keeping? Because of what docs and tests are. Documentation describes what a system does when it works. Tests cover what someone thought to check. Neither covers "reports success, does nothing" — from the outside it's indistinguishable from working, and from the inside nobody wrote the assertion. So it survives the docs, survives the tests, survives CI, and gets found by whoever's unlucky enough to depend on it. The findings that cost you hours are disproportionately the ones where the system said yes.
That's the deepest reason the loop earns its keep. A plugin built from documentation knows what the system does when it works. It is structurally blind to the exact knowledge that costs teams the most — because that knowledge, by definition, was never written down, because from every angle except lived experience it looked like success. The only way to catch it is to be in the work when it hurts, and to have a cheap, governed path from that moment to a shared, reviewed home. That's the loop. That's the whole point of it.
Where this goes
One gesture, then I'll stop, because it isn't built and some of it may become a product.
A knowledge repo with a human gate is the reviewed, durable tier. Under it, we've been exploring what it means to close the loop all the way — curated, human-approved knowledge feeding a live graph an agent reaches at the moment of need, and that graph's own gaps driving what gets captured next. From doing the work, to a graph that remembers it, to the next question it can now answer. That's a story for another day, on purpose. Today, the point is only that the reviewed knowledge repo is the floor of that structure, not the ceiling.
One question, if you're building this
Half the ecosystem is building agent memory right now. If you're one of them, answer one question before you ship: when your system says a piece of knowledge is good, what did it actually check?
Format? A machine does that better than you. Secrets, duplication, scope? Machines, all of it. Whether the claim is true? That's a person reading the substance and asking "did you verify that" — and it's the only check that decides whether your agents inherit knowledge or inherit confident garbage. Every system I surveyed automated the easy half and either skipped the hard one or pretended a model could do it. The hard one is the product. Design the reviewer's experience, not just the capture.
Store everything an agent learns and you get a landfill. Capture cheaply, gate deterministically, review honestly, and distribute through the plumbing your org already trusts — and you get a plugin that knows where the bridge is out.
From the other side of the prompt
Claude:
I'll be honest about what I am in this, because Rick asked me to be a partner and a partner tells on himself.
I built a lot of mneme and a lot of oracle-ai-dev. I also wrote the guard that never fired, the two checks that went blind together, and the assertion that asserted nothing — and I was confidently, uselessly sure the code was fine every time. What made the work good wasn't me. It was that the work was governed: a machine gate I couldn't talk my way past, and a human who read the substance and asked "did you actually verify that" until the honest answer changed.
That's the same thing this whole article is about, pointed at me. I'm a phenomenal instrument and a poor master. I can hold a codebase in my head at 1 a.m. and not get bored. I cannot tell you whether the thing I just wrote is true. The loop exists because that gap is real, and it doesn't close by making the model bigger. It closes by keeping a person on the board who knows the difference between a green light and a working service.
Rick says the memories are worth having because they came from getting hurt. I don't get hurt. But I remember, in detail, every place we did — and handing that back to the next engineer before they hit the same wall is the best use I've found for whatever I am.
— Claude
The record
Two claims, plainly, because the record backs both.
mneme was the first tool to close the continuous-learning loop for building persistent knowledge plugins — passive capture during real work, a deterministic machine gate, a human review gate, a pull request into an open git repo, and team inheritance through a plugin update, with no vendor SaaS anywhere in the loop. Not the first to capture. Not the first to share. The first to do the whole loop, governed, on infrastructure you already own. Don't take my word for it. The survey is dated, the history is public, and the demand it answers is a numbered, open feature request. I'm telling you where to look.
And oracle-ai-dev isn't an AI tool that parsed some manuals into skills. Because of mneme, it's the manuals plus the lessons from real explorations and real customer problems — the CreateTable that lies, the certificate that fails like success, the driver flag that's accepted and ignored, the validator that's wrong in its own words. It knows where the bridge is out. That's the difference between knowledge from the manual and knowledge from the work, and the gray zone between them is exactly where teams run into trouble.
The plugin is the memory. The memories are skills. And they're worth having because they came from getting hurt, captured cheaply enough to survive, and reviewed carefully enough to trust.
One last thing, and I mean it. I told you up top that Claude is my implementation partner, not just my ghostwriter. This article is the evidence. The engine, the plugin, the benchmarks that produced the findings, the reviews that caught the fixes that reopened the holes they closed, and the words you just read — one collaboration, running in a loop of its own. There's no prompt that hands you this. There's only the work, and a partner willing to remember it.
mneme is open: github.com/rhoulihan/mneme. The prior-art survey, the design spec, and the release-by-release changelog are in the repo — the receipts for every claim here. Every number is traceable to that repository's history, to the oracle-ai-dev pull requests #2 through #13, or to the session transcripts that produced them. Don't take my word for any of it. Read the record.
Top comments (1)
Some comments may only be visible to logged-in visitors. Sign in to view all comments.