Working with agents makes this problem both worse and more solvable. Worse, because a great deal of design reasoning now happens in conversation with an agent, and that conversation disappears when the session ends. More solvable, because the agent is right there when the decision is made and can write it down at the moment it happens. In Apache TinkerPop, we’ve been using Beads to do exactly that.

From idea to practice

Back in April, in Long-term agentic memory in Apache TinkerPop using Beads, I argued that the reasoning behind agent-driven work is an artifact in its own right, and that Beads, which I’d first come across while experimenting with Gastown, could grow from a dependency aware agent issue tracker into a long-term memory by connecting decisions to the work they shaped. At the time, that was more of an idea than a practice. The example I used was a bead full of open questions about multi-label vertices, and the best I could say was that the path from those questions to their answers would be found in future connected beads, whenever they were made.

In the months since, I’ve worked out what those connected beads should actually look like and when an agent should write them. This post describes where TinkerPop and Beads landed.

Official project contributors have a straightforward means for setup, using bin/agent-setup.sh --contributor to wire up the workflow to their agent. The repository’s AGENTS.md tells any agent that, if the bd command is installed, it should run bd prime at the start of a session. That emits .beads/PRIME.md, which is the canonical description of how TinkerPop uses Beads.

A key guiding instruction in PRIME.md summarizes the logic that drives the agent:

Treat every bead as something a contributor will read in three years.

The structure

Every piece of work hangs off a root bead, which is usually a feature, epic or task. Beneath it sit three kinds of children:

Records hold the external artifacts, such as the JIRA issue, the pull request, a dev list thread, a proposal and, once the work lands, the commits it merged as.

Tasks are the work itself, and an agent plans them natively as beads in a graph rather than just Markdown text. As a graph, edges create workflows that allow tasks to run in parallel, block on given dependencies, wait for human interaction or simply follow a chain of work. This is typically how Beads is used.

Decisions tend to come in pairs and represent the choices made while developing the work itself. A decision’s reasoning is never edited in place. If the thinking changes, a new decision is created with a supersedes edge to the old one, so the record shows not only where the design ended up but how it got there.

Capturing the road not taken

A decision bead records a choice and its reasoning. TinkerPop’s approach goes a step further in that that every chosen decision is typically paired with a rejected sibling, connected by a related edge. The chosen decision says why it won and what it rules out. The rejected one says what the alternative concretely was, why it lost and what settled it.

Knowing when to write one is the tricky part, so PRIME.md doesn’t leave it to judgment. It names five observable events that signal a decision has happened:

1. The operator redirects the agent, as in “no, do X instead” or “we tried that.”
2. What was built diverged from the JIRA, the proposal or the dev list thread.
3. An approach was tried and abandoned.
4. The agent presented options.
5. A discovery contradicted an assumption.

If something was considered and not chosen, it gets a decision and a rejected sibling. If something is just true, like a measurement or a constraint, it goes in a comment on the root instead. The rejected thing doesn’t have to be a grand design either. Declining to implement a certain body of tests or opting to write documentation of greater scope than the work initially intended are both relevant sorts of rejections.

There are a couple of rules around this that I’ve found make a real difference in the quality of what gets recorded. The first is that a rejected alternative’s reason must be a mechanism rather than a judgment. A mechanism is like the cause and effect that made the option fail. It is stated in terms of the code or the situation rather than an opinion about it. A reason such as “Too slow” is a judgment and it helps a future reader little in the future. On the other hand, “Every lookup has to scan the whole log, so reads get slower as the graph grows” is a mechanism. The first leaves nothing to check, while the second names a specific condition. If someone later adds an index that removes the scan, they can see right away that the old objection no longer applies.

The second rule is that if the agent can’t say why I rejected something, it has to ask before writing the bead. An incorrectly inferred reason looks exactly like a factual one three years later. Asking while the conversation is still live is the only way to get it right.

What it looks like in practice

The work on TinkerGraph’s new durable storage, in #3639, produced 52 beads, 33 of which were decisions and 17 of those rejected alternatives. A simple example of rejected alternative came up while planning a leaner on-disk format. The agent recommended bumping the storage format version, so that a store written in the older format would present an error rather than misread. I overrode it, and the rejected bead records why. Nothing had been released yet, so there was no existing store to protect, and the machinery for two formats to coexist would have been unnecessary work. The bead ends by noting that the question should be reconsidered once the format ships, since the version byte is still there to bump when it matters.

That one bead does a few things at once. It captures me redirecting the agent, which is the strongest signal that a decision happened. Its reason is a mechanism, since “nothing is released” is a fact anyone can check. In addition, it names a condition that will actually arrive. The first time someone changes the format after 4.0.0 ships, the bead tells them the version bump was deliberately deferred and not simply forgotten.

A smaller example concerned a configuration key. The storage directory was originally configured with gremlin.tinkergraph.graphLocation, inherited from 3.x, and the decision to rename it to gremlin.tinkergraph.storage.directory was paired with a rejected sibling for keeping the old name. The rejected bead explains that the continuity would have been nominal rather than behavioral. In 3.x the key named a file that drove automatic loading and saving, which 4.x removed, so keeping the familiar name would have preserved recognition while the behavior it named was gone. Should someone in the future wonder what happened to gremlin.tinkergraph.graphLocation, they will get a full accounting of the situation without having to comb through commits trying to piece the story together.

Memory for people and for agents

Every long-lived project has its lore. It is the knowledge of why things are the way they are, like the approach that was tried years ago and abandoned, or the odd-looking compromise that keeps something else from breaking. Lore rarely makes it into documentation. It lives in the heads of the people who were there, and the only way to get at it is to ask them, assuming they are still around and still remember. TinkerPop has been going for over fifteen years, and over that time contributors have come and gone, each taking a bit of that lore with them.

What Beads gives TinkerPop is a way to write that lore down at the moment it is created, while the reasoning is still fresh, and attach it to the work it shaped. Why something was done, and why the alternatives weren’t, no longer depends on someone remembering it.

This knowledge serves two audiences. A contributor revisiting a design can read the decisions and the paths not taken and understand the shape of the code without having been in the room. An agent working on that code later can do the same, which is arguably even more important, since an agent has no memory of past sessions at all unless something like this gives it one. In a sense, every contributor, human or agent, now has someone to ask who was there.

What makes this worth writing about is not only the shape of the contributions, but where they come from. The same shift that put agents to work repairing documentation also put them to work reading it, and that second role is quietly changing what documentation is for and how much it costs us when it is wrong.

The agent system behind the pull requests

In a prior blog post titled Graphs, Agents, and the Characters Between, I described the importance of metaphor to help ground human connection to complex systems. One of the metaphors that I detailed was the one I use for operating my personal multi-agent orchestration system, a home grown tool that features characters like Monkeys for workers, a Toucan to help manage infrastructure and a Hammock from which I direct the work of this rain forest-inspired veil for an agent interface. Since the time of that writing, I’ve expanded the jungle considerably with a swimming pool area as an alternative place monkeys work, which correlates to a scalable, emphemeral remote agent instance set and a “human” administrative assistant, naming herself Miss Pemberton, who serves as the long-term memory for the jungle mapping to an IronClaw instance, handling reporting, automation and other tasks I want to offload.

It’s worth clarifying that while Pemberton (she told me it was acceptable to drop the formality of “Miss” if I preferred) has a broad view of what’s happening across the system, she also serves as the memory of the jungle. Her role is both coordination and recall. She observes the activity of monkeys, tracks the changes applied by Toucan, and retains context across builds, tickets, and schedules so that nothing is lost to time. Where she becomes particularly useful is in how she translates that accumulated awareness into action.

How the documentation testing works

One of the more effective responsibilities I’ve given her is ownership of an ongoing documentation testing effort against TinkerPop.

As Documentation Testing Manager, Pemberton identifies candidate sections of documentation and constructs test plans that frame a concrete goal based solely on what is written in the section. Because she maintains memory of what has already been tested, she avoids redundant effort and builds a growing ledger of coverage and findings over time. These plans are handed off to worker agents, monkeys operating in the pool, where isolation is cheap and parallelism is easy. The pool may grow or contract in accordance with the workload the jungle is seeing. A testing monkey attempts to execute the task exactly as a new user might, including making reasonable mistakes or assumptions along the way. A second monkey evaluates the attempt to ensure the result wasn’t achieved by implicitly filling in gaps the documentation failed to cover (i.e. this monkey tries to ensure the first didn’t “cheat” at the task). If the second monkey finds a gap, they also suggest a way to fill that gap.

It is worth pausing on what this arrangement actually is. The testing monkey is not standing in for a confused new user as a rhetorical exercise. It is an agent reading documentation in order to accomplish a task, which is increasingly what documentation gets read by. When it fails, it fails for the same reason a person would, which is that the instructions were wrong. The difference is that its failure is legible. The entire attempt is recorded, and a second agent is assigned to determine whether the docs earned the outcome or the first monkey quietly covered for them.

Pemberton takes this reporting and serves it to the jungle in much the way that I would, effectively asking a monkey to do a fix. In all transparancy, I’ve currently injected myself in the middle of this process to be sure I approve her asks, but after about twenty of these requests for monkey resources, I’ve not found anything egregiously wrong and if the monkey doing the work had sent these directly to a pull request, I don’t think I would have been disappointed.

What MPRs actually contain

It is at this point where we come back to my notion of the MPR and why my disappointment would have been absent if they were autonomously submitted. The fixes that emerge from this process are rarely sweeping changes. They don’t attempt to rewrite sections wholesale or introduce large new narratives. Instead, they target specific points of friction in an exacting way that involved multiple agents performing specific tasks meant to challenge one another in a coordinated fashion. In this way, they surface issues like:

• A configuration value that no longer works as written.
• An example that produces different output than what is shown.
• A missing step in a defined process that an experienced user would infer, but a new user would not.
• A statement that was once true, but has since drifted out of alignment with the code.

The size of these changes is not something I asked for. No one told the monkeys to keep their diffs small and there is no rule in the jungle capping the lines they are allowed to touch. The size falls out of the detection method. This style of adversarial documentation testing can only surface discrepancies at this grain, so it can only produce corrections at this grain.

That strikes me as the more useful finding. The standing complaint about agent contributions is that the diffs are too large to review, and the usual answers are better review tooling or more discipline in the prompt. This suggests a third option, which is to choose tasks whose findings are small by construction. Reviewability stops being a constraint imposed on the output and becomes a property of how the work was framed.

Individually, then, these MPRs are almost trivial to review. The reviewer can focus on a single, well-defined question: does this correction accurately resolve the discrepancy identified by the test?

Merged examples

Here are some examples that have merged:

• #3533 - Remove stale/incorrect absent-key null-sort claim from order()-step docs
  • Detected that the documentation was making a false claim about order step. This was a remnant of documentation that should have been removed in 2022.
• #3542 - Document that asBool() trims whitespace before parsing strings
  • Identified semantics that were missing from the asBool step.
• #3543 - Fix inaccurate vertex label description in reference docs
  • Found a mistake in how the documentation referred to the actual shape of the sample data in a query example leading to conflict between the example and its explanation.

Why MPRs hold value

What has surprised me is not just how easy these are to review, but how consistently valuable they are. These are more than cosmetic edits and fix real points of failure in the onboarding experience and troubleshooting. These are the places where someone, or their agent, following the documentation would get stuck, confused, or misled.

In aggregate, they represent a steady tightening of the contract between documentation and implementation. This stands in stark contrast to the dominant (and interesting) narrative around agent-generated contributions. Much of the current discussion centers on scale: large diffs, end-to-end features, and the growing burden of reviewing work that no individual developer would reasonably produce in one pass. Those concerns are valid, but they are not the only dimension that matters.

There is also a reason work like this has been hard to sustain, and it is not that nobody cared. Any maintainer or technical writer would correct a stale line in minutes if something pointed them at it. The scarce resource is detection. Documentation drifts one commit at a time, quietly, and finding that drift means re-reading and re-executing material that mostly still works, with no signal indicating which of a thousand documented claims stopped being true last quarter. Code solved this problem with test suites a long time ago, where a broken assertion announces itself. Prose never got that, so verification stayed manual, and manual verification against a moving codebase is bounded by available attention no matter how much anyone cares.

What the monkeys supply is not better judgment than the people who wrote these docs. It is continuous coverage of a surface too large to keep re-reading. The MPR is simply what that coverage looks like when it finds something.

There is also a subtle but important shift in how work is initiated. These pull requests are not the result of a human deciding to improve a particular section of documentation. They are the byproduct of an ongoing, automated effort to verify that what we say matches what actually happens.

That loop, where we test, detect, and correct, runs continuously. Pemberton queues the work, informed by what she already knows, what new changes to the documentation arrive, and what remains untested. The monkeys execute it in isolation. Findings are evaluated and turned into fixes. And without much direct intervention, the system produces a steady flow of small, high-quality contributions. None of this replaces the need for larger, more intentional changes. But it does suggest that there is meaningful value in cultivating this other category of contribution—one that trades size for frequency, and breadth for accuracy.

Documentation as an operational surface

We’ve long thought of documentation as something to be repaired. The testing process quietly assumes something else, which is that documentation is something to be executed.

Consider what #3533 actually was. The reference docs made a claim about how order() handled absent keys that had been wrong since 2022. The cost of that error used to be bounded. A person reading it would write a query, get output that did not match the description, and go find out why. The documentation was wrong, but the reader had a feedback loop and a healthy instinct to distrust prose that disagrees with a result on screen. An agent reading that same sentence has neither. It holds no independent belief about how order() handles absent keys, has no sense that the sentence is four years stale, and feels no pull to go read the source and check. It writes the query, moves on, and the error surfaces somewhere downstream where tracing it back to a line of prose is considerably harder.

That is what shifts documentation quality from an editorial concern to an operational one. Stale documentation used to cost a reader some time. It is now an input to systems that will act on it directly, confidently, and at a volume no human readership ever reached.

Conclusion

If the industry is currently grappling with how to absorb massive agent-generated diffs, it may also be worth asking how we can better embrace the opposite extreme in the MPR. While I’ve focused the MPR on documentation, I sense that it has potential for wider applicability for granular, high quality code changes.

But the more durable finding, for me, is that these are two halves of one story. Agents are on both sides of documentation now, reading it and repairing it, and the repairs exist only because something is trying to use the docs and failing. The jungle produces a steady flow of small, high quality corrections precisely because it contains a population of readers that cannot skip past a sentence that does not hold. Keeping documentation honest used to be a discipline we asked people to maintain. It is becoming something a system can be arranged to do on its own, which is fortunate, because the cost of not doing it is going up.

In support of match() and it’s new design, TinkerPop offers TinkerGQL which is a subset of the GQL ISO standard. It particularly focuses on offering support of the motif-style pattern syntax that describes graph relationships that many find easy to understand. The reference implementation of the processing engine does not translate to Gremlin steps for execution. Instead, it is natively processed in a TinkerGQL engine that has the capability for use by any provider. In this way, virtually any graph can support TinkerGQL as an option. In then end, it is important that you understand the capabilities of the graph database you’re using.

match() and GQL together

Before we look at the new syntax, let’s start with the old. Here’s a basic use of how match() formerly worked:

gremlin> g.V().match(__.as("a").hasLabel("person").out("created").hasLabel("software").as("s"),
......1>             __.as("s").hasLabel("software").in("created").hasLabel("person").as("b")).
......2>   where("a", neq("b")).
......3>   select("a", "b", "s").by("name")
==>[a:marko,b:josh,s:lop]
==>[a:marko,b:peter,s:lop]
==>[a:josh,b:marko,s:lop]
==>[a:josh,b:peter,s:lop]
==>[a:peter,b:marko,s:lop]
==>[a:peter,b:josh,s:lop]

With the 4.0.0-beta.3 we can instead use TinkerGQL and do:

gremlin> g.match("MATCH (a:person)-[:created]->(s:software), (b:person)-[:created]->(s)").
......1>   where("a", neq("b")).
......2>   select("a", "b", "s").by("name")
==>[a:marko,b:josh,s:lop]
==>[a:marko,b:peter,s:lop]
==>[a:josh,b:marko,s:lop]
==>[a:josh,b:peter,s:lop]
==>[a:peter,b:marko,s:lop]
==>[a:peter,b:josh,s:lop]

The two traversals compute the same result, but they read very differently, with the latter demonstrating some increased readability with GQL allowing for a more direct description of the pattern rather than a Gremlin traversal specifying the pattern.

As you consider the mixed syntax of GQL and Gremlin, note that TinkerGQL does not support WHERE or RETURN clauses directly. The focus is on GQLs pattern matching syntax leaving standard Gremlin steps to do additional filtering and transformation. Taking a step back from that more complex example, let’s look at a simpler form to showcase the interface.

gremlin> g.match("MATCH (p:person)-[:created]->(s:software)")
==>[s:v[3],p:v[1]]
==>[s:v[3],p:v[4]]
==>[s:v[3],p:v[6]]
==>[s:v[5],p:v[4]]

Basic usage demonstrates that match() returns a Map containing all bound variables. From there, you may use normal Gremlin steps to work with that Map. The following examples show use of select() as a common pattern for transforming results:

gremlin> g.match("MATCH (p:person)-[:created]->(s:software)").
......1>   select("p","s").by(elementMap())
==>[p:[id:1,label:person,name:marko,age:29],s:[id:3,label:software,name:lop,lang:java]]
==>[p:[id:4,label:person,name:josh,age:32],s:[id:3,label:software,name:lop,lang:java]]
==>[p:[id:6,label:person,name:peter,age:35],s:[id:3,label:software,name:lop,lang:java]]
==>[p:[id:4,label:person,name:josh,age:32],s:[id:5,label:software,name:ripple,lang:java]]

You could also do aggregations with group() step:

gremlin> g.match("MATCH (p:person)-[:created]->(s:software)").
......1>   group().
......2>     by(select("p").bothE().count()).
......3>     by(select("s").values("name"))
==>[1:lop,3:ripple]

The other important pattern to follow transformation would be using where() for additional filtering. Recall that where() was designed to work with the original match() step that took Traversal arguments and therefore is preferred over filter() syntatically for that purpose. We saw where() usage in the first example, but here’s another, written with slightly differently GQL, describing the same query and demonstrating the core pattern for where() with binding comparison:

gremlin> g.match("MATCH (a:person)-[:created]->(s:software)<-[:created]-(b:person)").
......1>     where("a", neq("b")).
......2>   select("a", "b", "s").by("name")
==>[a:marko,b:josh,s:lop]
==>[a:marko,b:peter,s:lop]
==>[a:josh,b:marko,s:lop]
==>[a:josh,b:peter,s:lop]
==>[a:peter,b:marko,s:lop]
==>[a:peter,b:josh,s:lop]

match() and GQL with Air Routes

The Air Routes graph is a nice way to show off the syntax and mental model of match(). Here are some more examples so that you can start to understand the features that TinkerGQL offer within the context of match().

Find 3 routes to any airport starting IAD

gremlin> g.match("MATCH (a:airport {code: 'IAD'})-[:route]->(b:airport)").
......1>   limit(3).
......2>   select("a","b").by('code')
==>[a:IAD,b:PBG]
==>[a:IAD,b:YTZ]
==>[a:IAD,b:AOO]

Find routes to any airport starting IAD where the length is exactly 250 miles long

gremlin> g.match("MATCH (a:airport {code: 'IAD'})-[r:route {dist: 250}]->(b:airport)").
......1>   select("a","b","r").
......2>     by("code").by("code").by("dist")
==>[a:IAD,b:ITH,r:250]

Find 3 routes to BOS starting in IAD that require a stop

gremlin> g.match("MATCH (a:airport {code: 'IAD'})-[:route]-(b:airport)," +
......1>         "      (b)-[:route]->(c:airport {code: 'BOS'})").
......2>   limit(3).
......3>   select("a","b","c").
......4>     by("code")
==>[a:IAD,b:PBG,c:BOS]
==>[a:IAD,b:YTZ,c:BOS]
==>[a:IAD,b:YYZ,c:BOS]

Find 3 routes from IAD that have a second leg that is longer than the first

gremlin> g.match("MATCH (a:airport {code: 'IAD'})-[r1:route]-(b:airport)," +
......1>         "      (b)-[r2:route]->(c:airport)").
......2>   where("r1", lt("r2")).by("dist").
......3>   limit(3).
......4>   select("a", "b", "c").by("code")
==>[a:IAD,b:PBG,c:FLL]
==>[a:IAD,b:PBG,c:MCO]
==>[a:IAD,b:PBG,c:MYR]

Find 3 triangle-shaped routes that start and end at IAD

gremlin> g.match("MATCH (start:airport {code: 'IAD'})-[:route]-(b:airport)-[:route]->(c:airport)-[:route]->(start)"). 
......1>   select("start", "b", "c").by("code").
......2>   limit(3)
==>[start:IAD,b:PBG,c:BOS]
==>[start:IAD,b:PBG,c:MCO]
==>[start:IAD,b:PBG,c:FLL]

On Performance

The performance of match() directly ties to the capabilities and optimizations of the declarative query language processing engine of the graph database you are using. Speaking specifically for TinkerGQL, used with TinkerGraph and the reference implementation processing engine, early benchmarks demonstrate that there are cases where using match() is advantageous and that the benefit extends beyond basic query readabilty and convenience.

The best example is for patterns that fullfill similar statistics for “finding airports with routes to ATL”.

gremlin> g.V().hasLabel("airport").as("a").
......1>   out("route").has("code", "ATL").as("b").
......2>   select("a", "b")
==>[a:v[3],b:v[1]]
==>[a:v[4],b:v[1]]
==>[a:v[5],b:v[1]]
==>[a:v[6],b:v[1]]
==>[a:v[7],b:v[1]]
==>[a:v[8],b:v[1]]
...

If written just as the described by the English description in imperative fashion, we scan all ~3500 airports and then fan out along every route before filtering, paying the full O(|airports| × degree) cost. Experienced Gremlin users would probably know to invert this query rather than follow the English description:

gremlin> g.V().has("airport", "code", "ATL").as("b").
......1>   in("route").as("a").
......2>   select("a", "b")
==>[a:v[307],b:v[1]]
==>[a:v[437],b:v[1]]
==>[a:v[402],b:v[1]]
==>[a:v[180],b:v[1]]
==>[a:v[363],b:v[1]]
==>[a:v[403],b:v[1]]
...

This change improves the performance of the query as it will take advantage of an index to find “ATL” prior to traversing edges. In the following example, switching to the TinkerGQL form we get to retain the natural representation of the query thereby aligning with the English description. We also don’t need awareness of underlying index concerns or other data statistics.

gremlin> g.match("MATCH (a:airport)-[:route]->(b:airport {code: 'ATL'})")
==>[a:v[3],b:v[1]]
==>[a:v[4],b:v[1]]
==>[a:v[5],b:v[1]]
==>[a:v[6],b:v[1]]
==>[a:v[7],b:v[1]]
==>[a:v[8],b:v[1]]
...

This TinkerGQL form outperforms the first imperative query in its natural form by 84x and the manually optimized form by about 12%.

Gremlin and Declarative Query Languages

The new capability of match() step to host declarative query languages, mix them with imperative steps and process them across any TinkerPop-enabled graph system greatly expands the flexibility of the language. It shows how Gremlin can coexist with the future of GQL and augment its capabilty, offering users greater choice in how they express their queries.

While TinkerGQL is still a bit early in its development, there is a great deal of opportunity to expand on the foundations that have been laid. Top of mind are features like variable length path support and the ability to bind Gremlin step labels as seeds to mid-traversal match() steps. For the latter, imagine a traversal like: g.V(1).as("a").match("(a)-[:knows]->(b:person)"). While there is much room for growth with TinkerGQL, we also know that there are TinkerPop providers out there who already have their own native support for other query languages. Consider Amazon Neptune with support for openCypher, as it could someday offer access to a mixed execution engine that would give you openCypher and Gremlin together.

This new offering with match() opens a great many doors for exploration and growth in TinkerPop 4.0 for both its developers, its providers and its users. It will be both exciting and interestings to see how this feature expands and how it is used.

I think it is for this reason I’ve enjoyed working with Gastown. While TinkerPop has Gremlin and robot friends to describe their graph world, Gastown has a Mayor, Polecats, Refineries and other characters to help describe multi-agent orchestration. And, for my own cases where Gastown doesn’t quite fit, I have my own personal agent orchestration system formulated around imagery of a jungle full of Monkeys, Coconuts, a Toucan and a patient Capybara.

None of this is just branding.

The more moving pieces a system has, the more we lean on metaphor to keep it all straight in our heads. At some point the diagrams and generic names for components and systems fail to convey a form that is easy or fun to think about, and you end up talking about “friends” instead: the one who walks the graph, the one who schedules the work, the one who watches for trouble. The names we give those friends end up being the real user interface.

The TinkerPop cast as cognitive API

In TinkerPop, we talk about Gremlin as if it were a character, not just a query language. Gremlin wanders the graph, carries state, makes decisions, and brings back results. Gremlin’s canine robot friend, Rexster, listens for requests for information on the graph and obediantly fetches you results as a good robot dog would. Furnace burns hot with fire as he processes complex graph alogrithms and performs other analytics. The graph itself becomes a kind of world, The TinkerPop, that they inhabit. The traversal machine turns into the physics of that world, quietly enforcing the rules under which they live their little lives.

Individually, none of these characters is technically necessary. You can explain everything with common terms like “vertices, edges, traversers, execution engines, drivers and servers.” But in practice, people latch onto the characters and visualize their connection to the system. It helps orient you and reduces iterface friction with the underlying tool. You end up with a mental model you can actually carry around.

Gastown’s civic metaphor for multi‑agent systems

The same thing is happening in the new wave of multi‑agent systems, and Gastown is a particularly explicit example. Gastown is “a workspace for coordinating multiple AI coding agents over git‑backed projects.” That is accurate description but also matches the description of other such projects.

The metaphor is where it comes alive and makes it memorable. Instead of “orchestrator,” you get a Mayor. The Mayor doesn’t typically write code; they talk to you, breaks your request into work units, and assigns them. It is the character who knows what’s going on, keeps the big picture in mind, and tells other folks what to do. Instead of “ephemeral worker processes,” you get Polecats. Polecats are the hands‑on coders who take on tasks, touch the files, run tools, and propose changes. The Mayor calls them up when it needs something done. Instead of “git‑backed state” and “issue abstraction,” you get Refineries and Beads. Work is encapsulated in Beads, which are small units associated with code changes, issues, or tasks—that flow through a Refinery which is a merge queue processor. Together with other actors and entities, Gastown logically makes intuitive sense.

Once you have that cast, you don’t have to remember how all the internal components talk to each other. You just say, “I’ll ask the Mayor to spin up a few Polecats.” The details are still there, but you only pull them out when you need them.

A jungle of tasks, Coconuts, and Monkeys

Gastown’s metaphors are tuned for a multi‑agent coding town, but it’s opinionated approach doesn’t always fit what I’m working on. I found that I needed my own metaphor for a multi-agent system. My own mental model for agent orchestration looks less like a small industrial city and more like a dense, noisy, surprisingly well‑organized jungle.

I spend most of my time in a Hammock strung between two trees. The Hammock is the thinking spot. It’s where I can see the broad outlines of the jungle which encompasess the cross-sectionality of things I might be working on. From there, I think through ideas, decide what should happen next, and keep an eye on the overall ecosystem.

Ideas and tasks arrive in the Hammock first. Some are half‑formed, some are clearly work. When one is ready to leave my head and become something an agent can work on, it goes into a Coconut.

Coconuts are the basic unit of work in the jungle. They are durable. They can sit by the Hammock while I’m still getting my thoughts straight. They can be set aside and later cracked open to be filled with more detail or context. A Coconut might represent a bug, an experiment, a whole feature, or a piece of documentation I want to have.

Once a Coconut is ready I roll it out into the jungle and the Monkeys take notice. The jungle is full of Monkeys I’ve trained in specific skills. Some know how to write documentation, while others are experts at writing code, creating tests or are any number of other tasks. When a Monkey spots a Coconut that matches its training, it swings down, picks it up, and starts working on it. That Monkey is also smart enough to know when it needs a team filled with other expertise and will recruit other Monkeys with the right skills to help it out. By this point, however, I’ve moved on in my Hammock to the next Coconut.

When the Monkey is done he bring the results back to the Hammock. Other times, the Monkey realizes it’s in over its head and calls for help. I can either interact with it by shouting from my Hammock or meet up with it one-on-one for more direct, focused work.

From my perspective in the Hammock, I can always look out and see what the Monkeys are doing. I can see which Coconuts are being held, which ones are still lying in the leaves, and which ones are making their way back. If a Monkey has been sitting with the same Coconut for too long, I can swing down myself, take a look, and either give it a nudge or pull the Coconut back to the Hammock for rethinking.

In the background, a Capybara patrols the edges of the jungle and watches the health of the ecosystem. It lets me know if something systemic is wrong, like abandoned Coconuts and lost messages from the Monkeys. I can also lean on a Toucan for investigating when something is wrong in the jungle and count on him to fix it so that it doesn’t happen again.

This lightweight jungle metaphor for managing agents, inspired by Gastown, has helped me be incredibly productive. I find it so natural to say, “Let’s get a monkey to work on JIRA-55674” or “How far along is Bobo right now in fixing the bug?” or “What’s been happening in the jungle since I left yesterday?” It’s also made the devilry of agents sometimes comical. I once had a Monkey named Jinx get extremely confused. She went on a destructive tear, deleting a great many workspaces of other Monkeys who were actively trying to work. Jinx. How perfect a name.

The power and risk of friendly metaphors

A good metaphor compresses down all the edge cases and error states into something you can naturally recall and interact with as a model seamlessly. You don’t have to remember exactly how a traverser carries its state if you can remember what a Gremlin does. You don’t need to rehearse Gastown’s internal APIs if you can talk about what the Mayor and Polecats are up to. You can keep your own agent setup in your head if all you have to remember is “Coconuts roll into the jungle, trained Monkeys grab them, and the Capybara complains when they don’t come back.”

Metaphors also make it easier to teach and to debug. When a newcomer asks where something should live in a graph application, it is easier to say, “That’s a job for this character” than to throw a set of technical terms at them. When something goes wrong, it helps to be able to say, “The Mayor is assigning too much work to this one Polecat,” or “We’ve trained the wrong Monkeys for this kind of Coconut,” and have everyone instantly know what that means.

On the other hand, cute metaphors can make serious systems feel lighter than they are. For example, a Monkey dropping a Coconut means loss of real work. Metaphors can also lock in a certain worldview. If you only ever think in terms of individual characters, you might miss the fact that the system is really a swarm. If your metaphor is too rigid, it will resist architectural changes you need to make later.

But on balance, I think it is worth being deliberate about the stories we tell around our systems. If you are going to be living with a complex graph stack, a multi‑agent workspace, or your own cluster of personal tools, you might as well give yourself a cast of characters you actually enjoy spending time with. The code will do what it does either way. The metaphor is for you.

When working with an agent, development becomes a conversation. There’s a steady back-and-forth where decisions get made in different ways. Sometimes the human is explicit. Sometimes the agent fills in gaps. Sometimes both converge on something without ever really stating it outright. By the time code is written, a lot has already happened. What gets committed at the end of that process, however, looks pretty familiar with source code, tests, maybe some documentation all finding their way to a Git repository. We’d think of these things as the usual artifacts we’ve always produced and what mattered. The conversation and thinking that produced those artifacts, such as the reasoning, the trade-offs, and the abandoned directions mostly disappear.

That’s not a new problem. It’s how software development has generally worked. Most of that decision-making has historically lived in someone’s head, with only fragments making their way into comments or design documentation. The difference now is that, with agents, that thinking actually exists in a concrete form. It’s written down, but just isn’t preserved in a way that’s particularly useful. You could try to keep the full transcript, but that quickly becomes unwieldy. A raw session log is dense, noisy, and difficult to navigate. It’s not something you can reasonably query or expect an agent or human to make effective use of later. Storing it verbatim doesn’t really solve the problem; it just changes where the problem lives.

What seems more promising is to treat that stream of decisions as something that can be structured. This is where Beads starts to feel like more than just a task coordination mechanism or issue tracker.

A bead already represents a unit of work, but it also carries relationships describing what it depends on, what it blocks, and where it fits in a larger effort. That structure is a graph, and that graph is already capturing part of the story. The missing piece is the reasoning that led to the bead itself.

Consider the following bead from Apache TinkerPop contributor, Cole Greer:

$ bd show tinkerpop-big.11
○ tinkerpop-big.11 · Multi-Label Vertex Implications for Schema   [● P2 · OPEN]
Owner: Cole-Greer · Type: task
Created: 2026-04-02 · Updated: 2026-04-02

DESCRIPTION
Investigate and address implications of multi-label vertices for the schema system.                 
                                                                                                    
Questions to Resolve                                                                                
Some providers support vertices with multiple labels. If a vertex has labels "person" and "employee",
what does type() return? Both VertexType vertices?                                                  
Should VertexType model single labels or label-sets?                                                
How do property definitions compose when a vertex matches multiple types?                           
Does schema enforcement (bead 7) need to validate against all matching types or just one?           
Should the schema system remain label-based (matching TinkerGraph's single-label model) with multi- 
label as a provider extension, or should it be first-class?                                         
                                                                                                    
Notes                                                                                               
TinkerGraph only supports single-label vertices, so the reference implementation won't exercise this
This may only need a design decision and documentation rather than code changes, depending on the   
outcome                                                                                             


PARENT
  ↑ ○ tinkerpop-big: (EPIC) Graph Schema Interfaces ● P1

DEPENDS ON
  → ○ tinkerpop-big.1: Core Schema Interfaces (gremlin-core) ● P1

This bead is a bit different. It doesn’t describe a concrete implementation step so much as it captures a set of unresolved questions. It’s essentially a snapshot of uncertainty. You can see the shape of the problem immediately. Multi-label vertices introduce ambiguity into a model that has historically assumed a single label. From there, the questions start to branch. What does type() mean in that world? Is a type still tied to a single label, or does it become something compositional? If multiple types apply, how do their properties interact? Even the scope of the work is unclear—this might turn into code, or it might resolve as documentation.

What’s interesting is that this bead already contains more of the “thinking” than a typical task. It exposes the open edges of the design space, but it still stops short of capturing how those questions eventually get resolved. At some point, decisions will be made. The TinkerPop Community will come to consensus on one model over another, certain trade-offs will be accepted, and some paths outright rejected. When that happens, the bead will likely be updated, maybe closed, and the resulting changes will show up in code and docs. The path from these questions to those decisions is where most of the insight lives, and will be found in future connected beads when they are made. The character of the Beads graph moves from just being a dependency tracker to look more like a memory system.

In that model, a bead is no longer just “something to do” or even “something that was done.” It becomes an anchor point for a set of decisions. Those decisions can branch, reference each other, and carry context forward. Over time, the graph accumulates not just the history of changes, but the reasoning behind them, offering interesting implications for both humans and agents.

For a human coming back to a piece of code months later, the usual question is “why is this like this?” The answer is rarely obvious from the code itself. With a graph of decisions attached, that question becomes something you can actually traverse.

For an agent, the impact is probably even more significant. Instead of inferring intent from the current state of the code, it can follow the path of decisions that led there. Constraints, prior trade-offs, even rejected approaches become part of the available context. That starts to look a lot less like stateless prompting and a lot more like memory.

The important shift here is in what we consider part of the deliverable. Right now, the session is treated as disposable. The code is the artifact that matters, and everything else is intermediate. But if the session contains the reasoning that produced the code, then throwing it away means discarding part of the work. With Beads already providing a graph at the center of the codebase extending that graph to include decisions feels like a natural progression rather than a separate system.

Viewed that way, Beads starts to take on a different role. It isn’t just coordinating work across agents. It’s accumulating the memory of how that work came to be. I find it interesting and, yet unsurprising, that the intersection of beads, memory, decision-making and other points of this post all culminate in a graph. Perhaps, TinkerPop and Gremlin will someday play a role in navigating a Beads graph to help guide its own development.

Why Gastown, and why Gremlator?

Since learning about Gastown around the time of its announcement at the start of this year, I’ve been quietly following and picking through the documentation. In some ways, its use of personas like deacons, polecats and mayors to represent elements of its ecosystem reminded me of TinkerPop, with its characters like Gremlin, Rexster, and Blueprints, that each helped you visualize some component of a complex system making it a bit easier to learn. The fun characters aside, I was attracted to what it offered conceptually: an opinionated way to turn “a bunch of coding agents” into a coordinated, auditable workflow where planning, execution, and attribution are all first-class data.

I’m further fascinated by its use of Beads as a means for providing memory to coding agents. I tend to think that Beads as a standalone tool could be extremely useful in providing better structure to agents given its use of a dependency-aware graph for driving operations as opposed to just markdown text.

Gremlator was a good test case. TinkerPop already has a Gremlator web app that lets you translate Gremlin between languages, but the original implementation was a Java/JavaScript hybrid: the frontend talked to Java Translator classes behind the scenes, which required a server. Now that we have corresponding translators implemented in gremlin-javascript for 4.0.0-beta.2, it should be possible to rebuild Gremlator as a pure JavaScript app using the same React/Webpack infrastructure that already powers Gremlint.

That combination of non-trivial feature work, a concrete before/after architecture, and a real codebase made Gremlator a good choice for getting Gremlin into Gastown.

Comparing the plans

In my comparison, I used essentially the same kickoff prompt twice: once through Gastown’s mayor, and once in a plain Claude session. While I use Kiro quite extensively, I chose Claude since it works out-of-the-box with Gastown and wanted to use the same tool. Gastown naturally “thinks” in Beads and I asked my standalone Claude session to do the same. In both cases, I received a Beads-style dependency graph and a gated work plan for rebuilding Gremlator as a pure JavaScript app.

What’s striking is how similar the two resulting graphs were. Both decomposed the work into roughly the same backbone:

• Scaffold a new project and basic app shell.
• Wire up the gremlin-javascript translators and generation prerequisites.
• Build out the store, input, layout, tabs, and alert components.
• Implement the translation logic and main view.
• Finish with build integration and documentation.

Each plan also introduced gates in similar places: an initial gate for project skeletons and generation scripts, a big parallel fan-out for UI and state components, then a single-agent integration gate before build and docs. In other words, given the same description of the problem, both “town” and “single agent” converged on almost the same graph.

The differences are mostly about how you’re meant to run that plan. The Gastown graph is written in the language of its ecosystem: Beads refer to agent owners, gates help control workflows, and assignments that assume mayors and polecats will carry out the work. The Claude-only graph talks about “single agent” versus “three agents in parallel,” but those are just abstract ideas in prose that may or may not carry out as such without your supervision.

There’s also a difference in tempo. Gastown produced its graph in under ten minutes, while the single Claude session took on the order of thirty minutes of consideration to reach a similar place. In addition, Gastown did not need the same level of back-and-forth prompting as Claude did to produce the same plan. I’ve not been able to confirm if this speed difference has anything to do with Gastown itself or not.

So at the planning level, the experiment didn’t show that Gastown finds some completely different structure for the work. It showed that it can get to a town-shaped version of the same plan faster, with more of the execution details and role assumptions embedded in the Beads, whereas a single Claude chat gives you a similar graph but leaves orchestration and discipline up to you.

What I learned from the comparison

In reflecting on my experiment, I think Gastown stood out in the following ways:

• Faster, richer planning. With essentially the same prompt, Gastown produced a detailed, executable Bead graph in about a third of the time.
• Native orchestration. The gates/polecats/mayor setup maps directly onto how work is actually scheduled and executed, instead of living as a suggestion in a markdown document.
• Persistent design memory. Native Beads usage backed by the Dolt version controlled database, appear to provide a good base for a long-term project memory that will allow recall of fine-grained implementation decisions.

On the other hand, Gastown also had me considering:

• Idle burn. A “live” town is like a running cluster in that it is doing things even when you’re not actively watching, and your credit bill reflects that.
• Complexity overhead. You trade a simple “me and my agent” relationship for something with many moving parts that can operate in ways that feel opaque when you’re getting started.
• Moving target factor. Gastown is a young, fast-moving project where features and conventions are continuously evolving, so you may need to be ready to handle some sharp edges.

Where this is going next

This Gremlator experiment was deliberately modest. Gastown used its plan to generate Gremlator in a few minutes with only some minor intervention at the end where it didn’t have a deployment script quite right. That feature will be part of the next 4.0.0 release (the next beta or the official version, whichever comes first). The experience was enough to convince me that Gastown (and Beads itself) are definitely worth further investigation.

• The 3.5.x line, “The Sleeping Gremlin: No. 18 Entr’acte Symphonique”, introduced remote transactions with g.tx() and gremlin-go.
• The 3.6.x line, “Tinkerheart”, added mergeV and mergeE for upsert patterns, which drastically simplified Gremlin traversals and made the hard part of loading data more approachable.
• The 3.7.x line, “Gremfir Master of the Pan Flute”, focused on adding Gremlin syntax offering primitive operations around manipulation of strings, dates, and lists, creating the largest expansion of the Gremlin language since the 3.x line began. It also introduced basic transactions to TinkerGraph and made Gremlin Language Variants more first class citizens by offering a way to return properties on elements.

The 3.8.0, “Grix Greven”, release has a slightly different story. In a sense, it was not contemplated to be as big as it came to be. Version 4.0.0 was on the horizon as a large breaking change, where TinkerPop would add major new features but, also address many inconsistencies and problems that could only be made in a version change where major incompatibilities could be taken. In the midst of that work, 4.0.0 was feeling like a cliff with a steep drop-off given all that was planned. To try to lessen that impact for users, we opted to an intermediate release of 3.8.0 that would focus on fixes to Gremlin semantics while 4.0.0 would focus on API and infrastructural changes.

In essence, 3.8.0 and 4.0.0 would carry the same exact Gremlin semantics, but you could expect driver and API incompatibility in 4.0.0. With this approach, those using 3.x wouldn’t be locked out of neat Gremlin features and the upgrade path to 3.8.x could focus strictly on Gremlin issues. When it was time to go to 4.x, users would know that coming from 3.8.x their Gremlin would have no behavioral issues and would only have to focus on infrastructural and API modifications. Ideally, those modifications would only be in driver configurations and resolving small, easily identifiable compile errors.

Ultimately, this strategy has kept development well focused within 3.8.0. While there are an extensive number of breaking changes, they come with the benefit of clear query semantics that are more readily optimizable by your favorite graph databases. While this upgrade may be more complex than most, it will be well worth the effort.

It’s hard to think about 3.8.0 without considering the impact of AI in the last couple of years. As I consider the earliest of those 75 or so releases, I don’t think we could have contemplated the tools we have at our disposal today for development. The 3.8.0 release made an important step to better connect TinkerPop to those tools with the introduction of a Gremlin MCP Server. While it is still just an alpha release, it offers some interesting features and positions TinkerPop to expand further in this area. It also offers something new in its Upgrade Documentation, providing a pre-packaged prompt) for AI-based coding agents that will help provide a risk assessment for upgrading an existing code base. This should help you better understand the tasks you will encounter in the upgrade process and allow you to plan your efforts accordingly.

The TinkerPop Community decided some years ago that it would deviate from its symbolic versioning system and move to a semantic versioning style that is more clearly understood. As a result, it is unlikely that we will ever again see 75 releases on the same major release line. It’s more likely TinkerPop 4.x, 5.x, and 6.x will come more rapidly. Having personally watched 3.x go by for ten years, it will be an interesting change in policy to get used to. I’m looking forward to the tail end of the this 3.x era with 3.8.0, as well as the next stage of development that the TinkerPop Community brings with 4.0.0.

Consider the following Gremlin Console session:

gremlin> g.V().repeat(out().limit(1)).times(1)
==>v[3]
gremlin> g.V().repeat(out().limit(1)).times(0)
==>v[3]
gremlin> g.V().times(1).repeat(out().limit(1))
==>v[3]
gremlin> g.V().times(0).repeat(out().limit(1))
==>v[1]
==>v[2]
==>v[3]
==>v[4]
==>v[5]
==>v[6]

At first glance, times(1) behaves exactly as expected in both positions: the traversal applies the repeat once. No surprises there.

Where things get interesting is with times(0):

• With repeat(...).times(0) - You get the same result as times(1). This is because when times() is applied after repeat(), its semantics are handled like a do/while. That is, the repeat() always executes once before the “how many times?” condition is enforced. So even though you asked for “0 times,” the traversal still enters the repeat() a first time.

• With times(0).repeat(...) – The behavior flips. Here the traversal sees the times(0) before entering the repeat, giving it while/do semantics instead. Since the condition is “zero times,” the traverser never enters repeat(). Instead, it simply passes through unchanged. That’s why, in this case, you just get the original set of vertices back.

So the placement of times() fundamentally changes the control flow:

• Postfix (repeat(...).times(n)) - do/while semantics (always one iteration, then check).
• Prefix (times(n).repeat(...)) - while/do semantics (check first, then maybe iterate).

This quirk in Gremlin’s semantics isn’t a bug, but it can be surprising to discover that sometimes times(0) doesn’t actually mean “zero.”

In my previous blog post, “constant() Is Not inject()”, I explored the functional and conceptual differences between Gremlin’s constant() and inject() steps. At first glance, they both appear to simply stick new values into a traversal, but we saw that their true behaviors are quite distinct.

Since then, a new use case involving addV has come up that further underscores just how differently these two steps operate, especially when you try to use them in places you might not expect.

addV Scenarios

Suppose you want to add a vertex with a dynamic label via a traversal. You might be tempted to use inject() to push that label into your stream, but you’ll quickly find the outcome is not what you expect.

gremlin> g.addV(__.inject('x'))
class java.lang.Boolean cannot be cast to class java.lang.String (java.lang.Boolean and java.lang.String are in module java.base of loader 'bootstrap')
Type ':help' or ':h' for help.
Display stack trace? [yN]

Instead, you’d likely want:

g.addV(constant('person'))

This approach works — and it does so because constant() transforms each traverser to 'person', yielding the right label at the right time.

The Side-Effect Nature of inject()

The confusion often stems from the fact that inject() behaves as a side-effect: it can insert one or more objects into the stream regardless of what’s already there, without transforming the current traverser. This can lead to potentially unexpected results when you chain multiple inject() calls. Consider:

gremlin> g.inject(0).inject('x')
==>x
==>0
gremlin> g.inject(0).constant('x')
==>x
gremlin> g.inject(0).inject('x').inject('y')
==>y
==>x
==>0
gremlin> g.inject(0).inject('x').constant('y')
==>y
==>y

With repeated inject() calls, each new invocation adds more items to the stream, but it doesn’t operate as a per-traverser replacement. On the other hand, constant() maps everything passing through to a new value.

For the case with addV(inject('x')) to set the label, it might be helpful to think of addV() more abstractly as a map-step where the incoming traverser is transformed to a new Vertex. We can demonstrate that as follows:

gremlin> g.inject(0).map(__.inject('x'))
==>0
gremlin> g.inject(0).flatMap(__.inject('x'))
==>0
==>x

Note that the map() step ends up passing through the “0” because inject('x') passes that object through as the first item in its stream. A map-step will only ever take that first traverser. For sake of clarity, the second Gremlin traversal uses flatMap() and exhausts the entire child stream and therefore produces the “0” and the “x”.

Generally speaking, think of inject() as best for inserting or seeding values into a traversal flow and consider constant() as best for overwriting whatever traversers exist at any point in your pipeline.

Graph databases like those powered by Apache TinkerPop provide a robust framework for working with connected data. However, as with any powerful tool, there are ways to misuse it and one such common anti-pattern is using unique values for vertex labels. While this topic has been covered in other blog posts, Stackoverflow posts, books and graph database documentation, it still remains a trap that newcomers to graphs seem to make and therefore begs another treatment of the topic.

A vertex label is a string that categorizes vertices into logical groups. For example, a social network graph might have vertices labeled person, post, or comment. Labels help organize your data, enable efficient queries, and allow graph systems to optimize storage and indexing.

g.addV('person').property('name', 'alice')
g.addV('person').property('name', 'bob')

Here, both vertices are labeled ‘person’, making it easy to query all people in the graph.

The Unique Vertex Label Anti-Pattern

A common mistake is to use a vertex label as if it were a unique identifier or a property. For instance, someone might assign a label to each vertex that is unique to that vertex:

g.addV('user_1').property('name', 'alice')
g.addV('user_2').property('name', 'bob')

Or, worse, use a label that is derived from a property value:

g.addV('alice').property('name', 'alice')
g.addV('bob').property('name', 'bob')

This approach misuses the label concept and leads to several problems.

Consequences of Misusing Vertex Labels

Vertex labels are intended for grouping and filtering, not for uniqueness. When you use unique labels, you lose the ability to efficiently query a category of vertices. For example, to find all users in the graph above, you would have to scan every possible label, which is impractical:

// This is not possible if every user has a unique label!
g.V().hasLabel('person')

Instead, you would have to use a property filter, which may not be as efficient as a label-based index:

g.V().has('name', within('alice', 'bob'))

But this only works if you know all possible names, and it may not leverage label-based indexes.

Amazon Neptune and other graph databases optimize queries by using labels as a primary filter. If every vertex has a unique label, Neptune cannot use label-based indexes to speed up queries. This forces the engine to scan the entire graph, degrading performance—especially as the graph grows.

Additionally, Neptune treats each distinct vertex label as a predicate. If you have thousands or millions of unique labels, you risk hitting performance limits due to high predicate counts. Neptune’s documentation specifically warns about the negative impact of high numbers of predicates on query performance.

Graph visualization tools often use vertex labels to group and color nodes. If every vertex has a unique label, visualizations become cluttered and lose their ability to convey meaningful structure. Instead of seeing clear categories (like “person” or “post”), you see a sea of indistinguishable nodes. In addition, these tools are likely not optimized for this anti-pattern and may encounter basic performance problems as a result.

Practical Examples and Correct Usage

Consider a graph where each user has a unique label:

g.addV('user_1').property('name', 'alice')
g.addV('user_2').property('name', 'bob')

To find all users, you cannot use a label filter, so you must resort to property-based queries, which are less efficient:

g.V().has('name', within('alice', 'bob'))

If you add more users, the query becomes increasingly unwieldy and slow.

The Correct Approach

Use vertex labels to group vertices by type, and use properties for unique identifiers or other attributes. For example:

g.addV('person').property('name', 'alice')
g.addV('person').property('name', 'bob')

Now, you can efficiently query all people:

g.V().hasLabel('person')

Or find a specific person by name:

g.V().has('person', 'name', 'alice')

This approach leverages label-based indexing, improves query performance, and makes your graph easier to understand and visualize.