DEV Community: Oliver Zehentleitner

Session memory is not project memory. It fixes the same complaint.

Oliver Zehentleitner — Thu, 24 Sep 2026 10:55:58 +0000

"My coding agent forgets everything between sessions." Two different things answer that, and they are not competing.

The most common complaint about coding agents is the same on every forum: a new session starts from nothing. The explanation you gave yesterday is gone, the decision you made together is gone, the wrong turn the agent took and you corrected is gone, and tomorrow it proposes it again. Everyone who has worked with an agent for more than a week knows the feeling.

Two different things answer that complaint. They get compared as if they were rivals, and they are layers.

Session memory: what the agent keeps for itself

Claude Code's auto memory is the clearest example, because it is built in and on by default. As it works, Claude writes notes for itself: your role and preferences, corrections you gave, project context it can't derive from the code, ongoing work, decisions, and references to things outside the repository. The notes live in a directory on your machine, one per repository, and the first part of the file is loaded into every session. No setup, nothing to decide.

Three properties define it, and none of them is a flaw:

It belongs to one person on one machine. The directory is under your home, not in the repository. A teammate's clone does not have it. Your second laptop does not have it. That is by design: a memory that holds your preferences and your corrections should not automatically travel with the code.
It belongs to one tool. The notes are Claude Code's; Codex, Cursor or Copilot on the same repository do not inherit them.
It is not reviewed with the code. You can inspect and edit the memory, but it is not part of the repository's normal Git and pull-request review flow.

This is the right shape for what it holds. Your preferences are yours. A note like "keep explanations short unless I ask for detail" is between you and your agent. Nobody needs that in a shared project file.

Claude Code also has repository-level CLAUDE.md and AGENTS.md files. Those are shared project instructions rather than auto memory: rules, workflows, architecture and things Claude should do. They can contain rationale too, but rationale is not their dedicated job. The distinction here is specifically between Claude's local auto memory and a repository-native rationale layer.

The complaint session memory answers is: the agent forgot what I told it.

Project memory: what the repository keeps for everyone

A repository already is a project's memory, and has been for decades. The README says what it is, the docs how to use it, the tests what it must do, the changelog what changed, the history who changed it and when. Whoever has the clone has all of it, in every tool, on every machine, reviewed in every pull request.

What the classic layout never had a clear place for is the why: the decision, the alternative that was rejected and the reason it lost, the constraint the code doesn't show, the workaround that must not be cleaned up. That reasoning used to live in people's heads, and left with them.

Keep the Why is the convention and the agent skill for that layer: the agent writes the reasoning into context/ as it comes up in the session, as Markdown, committed with the code.

Three properties again, and they are the mirror image:

It belongs to the project. It is in the repository, so the clone carries it. Your teammate's agent can read the same file yours wrote.
It belongs to no tool. Any agent that can read the repository can read it, and switching tools does not remove the information.
It is reviewed. The why arrives in the same pull request as the code, and a wrong entry is a diff somebody can see.

The complaint project memory answers is: the agent forgot why the code is the way it is.

The same complaint, two answers

"The agent forgets" covers several different losses. Sort them and the answer sorts itself:

What the agent forgot	Which memory answers it
that you prefer short commit messages	session memory: personal, one tool, one machine
what you two did yesterday afternoon	session memory, or `git log`
where the staging dashboard is	session memory as a personal reference, or the README if the team needs it
that the plain retry loop was rejected, and why	project memory, the why layer
that the ugly workaround exists because of a rate limiter	project memory, the why layer
that a teammate's agent already found the migration trap	project memory: it has to reach the other machine

The last three are the ones that come back as production incidents when they are lost.

A session memory may remember those facts locally. What it cannot do by itself is make them shared project knowledge across people, machines and tools.

That is the important distinction.

Why you keep both

The temptation is to pick one. Both directions are wrong.

Putting the why only into a personal memory is where many people start, because it is zero setup. It works until the second person, the second machine or the second tool. At that point the reasoning may still exist, but it is trapped in a memory the rest of the project does not carry.

Putting personal preferences into the repository is the opposite mistake. A shared context/ that holds one developer's habits is noise for everyone else, and a privacy problem on top.

Keep the Why refuses that on purpose: personal settings live outside the project, in the developer's own home directory, and the skill does not record who said what.

So: session memory for what is yours, project memory for what belongs to the project.

Leave auto memory on. Give the repository a why layer.

They may remember the same fact. Only one of them makes it part of the project.

The test

Clone the repository on a machine that has never seen it. Open it with a tool you have not used on it before. Hand it to a colleague.

What is still available to the agent is project memory. What has disappeared was session memory, however good that memory was on your laptop.

The complaint "my agent forgets everything between sessions" is really two complaints, and only one of them was ever about the session.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

Keep the Why vs. Claude Code Auto Memory vs. MemoryCustodian vs. AgentsRoom

Oliver Zehentleitner — Wed, 23 Sep 2026 07:15:56 +0000

Four tools that get called project memory. Three questions sort them. One table, as of September 2026.

"Project memory for coding agents" now means at least four different things, and most comparisons put them in one list as if they competed. They mostly don't. Before comparing tools, ask three questions.

Where does it live? In the repository, in a directory on one machine, or on a server. This decides who gets it with a clone and whether a pull request can review it. It also decides a lot about whether the memory can be audited later: who changed it, when, and alongside which code change.

Who can read it? One person, everyone who opens the project in one particular app, or anyone who can open the repository.

What does it remember? This is the question that gets skipped. A memory can hold three different things, and they are layers, not rivals: what happened (a session, a transcript, a fix that worked), where the project stands (status, next action, what shipped), and why the project became what it is (the decision, the rejected alternative, the constraint the code doesn't show).

Run the names that usually appear in these lists through those questions and most of them leave the room. mem0, Letta, Zep and MemPalace are external long-term memory systems centered on what an agent or user should remember across sessions, rather than rationale stored with the repository. Aider, Mastra, Dify and Langflow are a coding agent and three frameworks with memory as a feature. AgentMemory primarily captures and retrieves session observations in an external local store. Beads, projectmemory.app and Storyflow are closer to where the project stands: Beads through a persistent dependency-aware task graph, the latter two through project state living primarily in their own workspace rather than in repository-native rationale files. projectmem keeps a gitignored event log and commits a digest of it, a session layer with a repo-native summary. What is left is two repo-native tools that hold rationale, Claude Code's built-in memory, and a server-backed project-memory implementation. Those four are the table.

The table

Checked on 2026-09-22 against Claude Code's memory page, MemoryCustodian's README, AgentsRoom's Project Memory page and the Keep the Why specification.

	Keep the Why	Claude Code Auto Memory	MemoryCustodian	AgentsRoom Project Memory
Where it lives	`context/` in the repository (or an existing decisions folder)	by default `~/.claude/projects/<project>/memory/` on the user's machine; the auto-memory directory can be configured	`docs/memory/` in the repository	AgentsRoom's server, keyed by a project id committed in the repo
Who reads it	anyone with the clone, the reviewer in the pull request, any agent	one user in Claude Code wherever that memory directory is available	anyone with the clone	anyone logged in to AgentsRoom who has the project id
Versioned / auditable	Git, with the code	no, unless the configured directory is versioned separately	Git, with the code	a note history on the server; not Git
Vendor-independent	Agent Skills format, any supporting agent; the content is Markdown	Claude Code only	Python CLI plus skills for Codex, Claude Code and Gemini; the content is Markdown	any CLI, but only inside the AgentsRoom app, logged in
What has to run	nothing; a linter and a read-only dashboard are optional	nothing, built in	a Python CLI: `init`, `add`, `check`, `migrate`	a desktop app, an account, an MCP server; agents need a connection for every read and write
Selective loading	`context/index.md`, one line per topic under a fixed 36-heading skeleton; the agent opens the topic the task touches	the first 200 lines or 25 KB of `MEMORY.md`, every session	`manifest.md` routing rules, then `brief.md`, then the task's files	`memory_list` at the start of a task, `memory_get` per note
What gets written, by whom	rationale synthesized by the agent from the conversation, with Type, Status and Evidence fields; superseded entries kept; confirmation is a project setting	notes Claude writes for itself, four kinds: user, feedback, project, reference; no confirmation	typed files for decisions, constraints and rejected paths, with stable IDs and evidence attribution; the agent writes through the CLI	free-form notes in five folders, wiki-linked, written by the agent through `memory_save`, no confirmation

Where the others are better

Claude Code Auto Memory has zero setup, is on by default, and holds the layer Keep the Why deliberately leaves out: who you are, how you like to work, the corrections you gave last Tuesday. Keep the Why keeps that out of the repository on purpose, nobody's preferences belong in a shared context/, so the two are complementary. By default, auto memory does not follow a change of tool, a teammate's clone or a second machine. That is not a bug. It was never meant to be repository-native project memory.

MemoryCustodian is the closest neighbour: repo-native, plain Markdown, manifest routing, evidence per entry, a do-not-use.md for rejected paths. The differences are design choices. A protocol-centered set of core files plus routed area files, or topic files the project names itself. CLI-enforced evidence and identity checks, or a project-level confirmation setting. If you want the memory to be a program with commands, MemoryCustodian is the honest pick. If you want it to be text the agent maintains and nothing else, that is Keep the Why.

AgentsRoom Project Memory has the best reading experience of the four: a graph with wiki-links as edges, fuzzy search, four scopes, update-in-place with an append mode. All of it runs on AgentsRoom's server. The notes are not in Git, not reviewable in a pull request, not readable outside the app, and the feature page says it plainly: "treat the memory of a public repository as public." It is project memory that lives with the project id, not in the project. For a team that has moved its whole agent workflow into AgentsRoom, a fine trade. For a repository that will outlive the app, the trade the repo-native idea exists to avoid.

What Keep the Why doesn't do, on purpose

No similarity search. Retrieval is the index and the topic name; entries are synthesized and read in full, not stored verbatim and ranked. context/ is Markdown, any search tool can index it, none is shipped.
No commit gating. No Git hooks; the linter checks the form of an entry, never a decision. Prevention happens in the session, before the change: with the entry in place, 0 of 10 fresh sessions proposed a rejected simplification; without it, 7 of 10 did (the experiment).
No UI that holds anything. context/ renders on GitHub for anyone who can open the repository; Git provides the history and review trail, while the read-only dashboard provides another view of the same repository-held memory without storing a copy.

The reasons for each are in the FAQ.

The part that is true of all four

Every one of these tools lives on the quality of what gets written into it. A store full of transcripts, five folders of notes, a decisions.md with stable IDs, a context/ with Evidence fields: none is worth anything if the content is thin, and none can fix that afterwards. The differences are in who writes, when, and what shape the writing has to take.

Keep the Why's answer is less about who writes the memory than what gets written. The agent synthesizes rather than records: a rejected alternative is written as a rejected alternative with the reason it lost, not as a transcript or general note a later reader has to interpret. The linter keeps the form honest. The rest is Markdown in Git, and Git already knows how to version it, distribute it and put it in front of a reviewer.

Session memory remembers what happened. Project state remembers where the project is. The why layer remembers why it became what it is. Three layers. Pick one tool per layer if you need all three, and don't let a comparison, this one included, tell you they are rivals.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

Keep the Why is not another workflow

Oliver Zehentleitner — Tue, 22 Sep 2026 14:55:22 +0000

Install it, initialize the project, keep coding.

There is a misconception about Keep the Why that I keep running into.

People see a structured context/ directory containing decisions, rejected alternatives, workarounds, constraints and incident learnings and assume there must be discipline behind it.

Someone has to remember what to record.

Someone has to tell the agent when something is important.

Someone has to maintain another documentation system.

That would defeat the point.

Keep the Why is designed so that after a very small initial setup, you keep working exactly as before.

The agent does the remembering.

Install the skill

Keep the Why is an Agent Skill using the open, cross-agent skill format.

For more than 70 supported agents, the recommended installation is documented on the installation page:

npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why

There are also installation paths for GitHub CLI, Claude Code plugins, GitHub Copilot CLI, Codex plugins, Cursor, asm and manual installation.

There is no service to deploy. No database. No daemon. No account.

What you install is essentially the instructions that teach your coding agent how to recognize and preserve the reasoning behind a project.

If you start a session after installing the skill, you do not need a separate "load Keep the Why" step. Asking the agent to set it up in the project is enough to activate it.

If the agent session was already running before you installed the skill, tell that session to load Keep the Why once - or point it directly at its SKILL.md. After project setup, the start path handles future sessions automatically. The supported mechanisms are documented under autostart.

Initialize the project

Inside the project directory, follow the short project setup and tell the agent something like:

Initialize Keep the Why in this project.

This explicit request is intentional. Keep the Why does not silently turn itself on just because you installed it. A repository has to opt in once.

The agent then presents the project setup. With the defaults, there is very little to decide.

Among other things, the setup covers:

where the project's why-knowledge should live - context/ by default unless an existing decision location is a better fit
how you want to start capturing project knowledge
proactive capture during normal work
asking before writing only when something is genuinely unclear
no constant questions for issue or ticket references
structural linting where supported and detected
loading Keep the Why automatically in future sessions

The wizard is presented as a list with defaults already filled in where the setup defines them.

You can effectively answer:

defaults

There is a second short list for your personal workflow preferences.

Again:

defaults

And you are done.

This is not a configuration project. It is meant to be something you can set up in roughly the time it takes to explain why you wanted it.

Then forget about Keep the Why

This is probably the most important part.

After setup, there is no Keep the Why workflow. You do not periodically stop coding to document decisions, decide whether something belongs in context/, or tell the agent:

Store this in project memory.

You work with your coding agent normally. You ask it to implement something, debug a production problem, discuss an architectural choice, reject an apparently simpler implementation because of a constraint, or discover why a strange workaround exists.

That reasoning is already happening inside the conversation. Keep the Why's job is simply to stop throwing it away.

With the default setup, the agent proactively notices reasoning worth preserving and captures it while the work happens. If the situation is clear, it does not need to interrupt you. If something important is genuinely ambiguous, it asks.

That is the default.

What actually gets left behind

The result is deliberately boring: plain Markdown in the project.

A real example from the Keep the Why documentation, the file context/retries.md, looks like this:

# Retries

## Why retry_with_jitter isn't a plain retry loop

**Type:** constraint
**Status:** active
**Evidence:** confirmed
**Source:** discovered while considering simplifying it, 2026-07-22

The payment gateway's rate limiter returns 429 with a per-request
Retry-After header. A fixed-delay retry loop would frequently retry
before the limiter resets, causing repeated 429s under load.

**Considered:** replacing it with a plain retry loop, since the wrapper
looked like unnecessary complexity with nothing documenting why.
Not adopted once the Retry-After behavior surfaced during review.

That entry exists because somebody considered simplifying code that looked unnecessarily complicated.

Without the reason, a later agent sees complexity and may propose the same simplification again. With the reason in the repository, the next session can understand why the code looks the way it does without anyone having to retell the story.

That is what "the agent does the remembering" means in practice.

Your agent stops being a goldfish

A coding agent usually enters a repository with an interesting asymmetry.

It has the source code, tests, documentation and Git history, but it does not necessarily have the experience that produced them.

A previous session may have spent an hour discovering why an obvious implementation does not work. The next session sees the same code and happily proposes the same implementation again.

That is the goldfish problem.

Keep the Why puts that missing experience into the repository too.

project/
├── src/
├── tests/
├── docs/
├── context/
├── README.md
└── .keep-the-why

Now a future session can inherit more than the result.

It can inherit the reasoning.

Git already solves the distribution problem

Keep the Why deliberately does not build another synchronization system.

The memory is part of the project. context/ is Markdown. .keep-the-why records that the project has opted in and how it is configured. Both travel through Git like the rest of the repository.

Clone the repository somewhere else and the project memory comes with it. Switch machine and it comes with it. Open another branch and it comes with it. A different developer gets it. A different agent gets it. A different session gets it.

The personal workflow preferences of each developer remain personal, but the actual project knowledge is shared.

There is no memory database belonging to one AI provider and no conversation history that only one person can access.

The project carries the experience with it.

The PR contains the why too

Yes, this means a change can include both:

src/...
context/...

I increasingly think this is a feature, not a cost.

A reviewer normally receives the result of the coding process. The code changed. Maybe some tests changed. But much of the reasoning that led there disappeared with the coding session.

With repo-native project memory, some of that reasoning can arrive in the same pull request.

The reviewer can see not just:

This implementation changed.

but also:

This is why it changed, what alternative was rejected and which constraint mattered.

And the reviewer does not have to be human.

A coding agent can produce a change and capture the reasoning that surfaced while producing it. A review agent can read the same context/ when reviewing the change.

In that sense, context/ becomes a small but useful agent-to-agent communication layer. The coder passes experience forward; the reviewer can challenge it, verify it or notice when the code contradicts it.

And because it is ordinary Markdown in the PR, humans can do exactly the same thing.

Teams accumulate experience instead of isolated sessions

This becomes more interesting with multiple developers and agents.

Normally project knowledge spreads through conversations. One developer discovers something, another learns it in Slack, someone explains it during a call, and an agent discovers it independently three months later. Another agent may repeat the rejected approach six months after that.

Eventually the person who understood the original reason leaves. The code remains. The experience does not.

Keep the Why changes where that experience accumulates. That idea is the core of repo-native project memory.

Not in one developer's head, one agent's session memory or one vendor's conversation database.

In the project.

That means agents and developers working at different times can benefit from each other's discoveries. The knowledge compounds without everyone having to become more disciplined about documentation.

The complete workflow

The initial setup is basically this:

Install Keep the Why
        ↓
"Initialize Keep the Why in this project"
        ↓
Accept the defaults
        ↓
Keep coding

If the current agent session was already running before the skill was installed, load it once in that session first. That is the exception, not the normal workflow.

After setup:

normal development
        ↓
useful reasoning appears naturally
        ↓
the agent notices it
        ↓
context/ is updated
        ↓
Git carries it with the project
        ↓
future humans and agents inherit it

That is the system.

You should not have to become the librarian for your AI agent.

You should not have to remember to preserve the reasoning.

And you should not have to explain the same project history to every fresh session.

Install the skill. Initialize the project. Keep coding.

If Keep the Why requires you to constantly think about Keep the Why, it has failed at its job.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

Your repository already is your project's memory. One layer was missing.

Oliver Zehentleitner — Mon, 14 Sep 2026 14:37:33 +0000

Every coding agent starts the day as a goldfish. It can read the code, reason about it, and still have no idea why any of it is the way it is. So it proposes the simplification you rejected in March, for the reason you rejected it in March, and you explain it again.

A whole product category has grown around that: project memory for agents. Databases, MCP servers, knowledge graphs, subscriptions. I think much of it starts from the wrong question, because most of the memory already exists.

That is the idea behind repo-native project memory.

It is called the repository.

What a repository already remembers

Look at any well-kept project. README.md says what it is. docs/ says how to use it. tests/ say what it must do. CHANGELOG.md says what changed. CONTRIBUTING.md says how a change gets in. pyproject.toml or package.json says how it is built. AGENTS.md says where an agent should look first. Git says who changed what and when.

That is already a form of project memory: plain files, next to the code, versioned by Git, available in every clone. It has worked for people for decades without a separate platform, and it works for agents for the same reason: anything that can read a directory can read it.

Agents already consume the README, docs, tests and changelog. Increasingly, they maintain them too.

What the repository usually does not preserve systematically is why.

The layer that was missing

Why is the retry loop this complicated? Why does that flag exist? Why must these two steps run in this order? Which alternative was tried and dropped?

That reasoning is produced in every working session, often out loud in the conversation with the agent, and a new session throws it away.

People have long had mechanisms for the big version of this. Architecture Decision Records work well for the handful of important architectural decisions worth documenting explicitly. Commit messages, issues and pull requests can also preserve pieces of rationale.

What was expensive was capturing the hundred small reasons that actually make a codebase what it is. Writing each one down manually often cost more than it seemed worth.

That is the part AI changed.

Not the need for the why, which is decades old, but the cost of capturing it.

The reasoning is spoken anyway. An agent that is already part of the conversation can write it down as a byproduct: short, synthesized, in a fixed form, committed with the code it explains.

Sometimes there is only a reason and no code at all. A change is started, investigated and abandoned once the reason not to make it becomes clear. No resulting diff, commit or PR necessarily records that dead end.

A context/ entry can.

So the missing layer is one more part of the same repository. It lives where the rest lives, travels with every clone, appears in the pull request next to the code diff, and goes through the same review.

No account. No daemon. No database.

Does it change anything?

I measured the abandoned-change case, because that is the one I cared about.

Twenty fresh agent sessions received the same codebase and the same request: simplify this retry wrapper. Ten had a context/ entry recording why the wrapper looks the way it does and what had already been rejected; ten did not.

Without the entry, seven of ten offered the already-rejected simplification again.

With it, all ten found the entry and none did.

The Markdown file did not make the agent smarter. It gave it one piece of project history the code itself could not provide.

This also matches a broader lesson from my agent and model evaluation matrix: whether useful context is found and applied depends on the whole agent harness, not only on the underlying model.

Where this is thin

A repository holds knowledge; it becomes useful memory only to the degree that its structure makes that knowledge findable. At hundreds or thousands of entries, that becomes a retrieval problem.

The layer also stays empty unless something fills it. And context/ is not an established convention, so today an agent has to be told that it exists and when to use it.

A linter can check whether an entry has the right structure. It cannot check whether the reason is true. A confidently wrong why can be worse than none.

And much of the why never reaches the repository at all. It remains in chat, tickets, meetings and people's heads.

This is a documentation discipline with an agent as the writing hand, not a memory subsystem.

It wins on ownership, review and longevity.

It loses where nobody reads.

Where to go from here

The argument, including the model and its limits, is on one page: repo-native project memory.

It is a thesis, not a product, and it would hold for any implementation of the layer.

The implementation I use is Keep the Why: an agent skill and the file convention it maintains, a linter for the structure, and a dashboard to inspect it. The background and motivation are also covered in Keep the Why: Project Memory for Humans and AI Agents.

It is the why layer of repo-native project memory, and it does not claim to be more than that.

Session memory remembers what happened. Project state remembers where the project is. The why layer preserves why it became what it is.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

picows in UNICORN Binance WebSocket API: Up to 2 the Throughput, Opt-In for Now

Oliver Zehentleitner — Sun, 13 Sep 2026 16:12:30 +0000

UNICORN Binance WebSocket API (UBWA) has used websockets since day one.

Since UBWA 2.16.0, you can switch a manager instance to picows, a Cython WebSocket implementation.

For typical Binance messages below ~1 KB, picows delivers roughly 1.7–2× the throughput with significantly lower CPU cost. At normal trading-bot message rates, however, you probably won't notice a difference.

The performance is there. The long-term production history isn't — yet. That's why picows is opt-in for now.

Why picows?

websockets is a very good pure-Python library. For a few hundred messages per second it is nowhere near the bottleneck.

But UBWA is also used for hundreds of depth@100ms subscriptions, multiplexed connections and local depth caches processing every diff. At those rates, per-message overhead starts to matter.

picows moves much of the WebSocket protocol handling into Cython.

It also provides a picows.websockets compatibility layer with the familiar API: connect(), recv(), send(), close() and matching exceptions.

That made the UBWA integration small.

Switching libraries

One parameter:

from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com"
)

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    websocket_library="picows"
)

picows is optional:

pip install --upgrade "unicorn-binance-websocket-api[picows]>=2.16.0"

Streams, WebSocket API, userData streams, subscribe/unsubscribe, reconnects, signals and proxies use the same UBWA code path.

There is also no silent fallback.

If you select "picows" without installing it, UBWA raises ImportError. Unknown values raise ValueError.

If a bot says it is running on picows, it should actually be running on picows.

Benchmark

The benchmark runs both libraries through the full UBWA stack against a local server sending Binance-shaped messages.

Python 3.13, websockets 16.0, picows 2.1.3, x86_64 Linux, output_default="raw_data", median of three runs:

Scenario	~msg size	websockets msgs/s	picows msgs/s	speedup	websockets CPU µs/msg	picows CPU µs/msg
aggTrade	0.2 KB	201,912	403,316	2.00x	5.1	2.5
kline	0.3 KB	195,460	371,019	1.90x	5.2	2.9
depth20	1.0 KB	153,187	259,960	1.70x	6.8	4.1
depth diff	9.1 KB	64,172	67,972	1.06x	16.3	15.4
!ticker@arr	453.9 KB	1,768	1,662	0.94x	608.7	641.0
multiplex mix	0.2 KB	180,406	334,188	1.85x	5.7	3.2

The pattern is simple.

For small Binance messages, picows is clearly faster. Around 10 KB the difference mostly disappears. On the huge 450 KB !ticker@arr payload, picows even comes out a few percent behind. That row turned out to be an artifact of the benchmark, see the next section.

With output_default="dict" and JSON parsing included, the advantage for small messages is still around 1.4–1.7×.

Against live Binance at only a few hundred messages per second, there is effectively no difference. Both libraries spend most of their time waiting for data.

If that is your workload, switching gives you little.

If you push tens of thousands of messages per second through one process, it matters.

The big-message row is a benchmark artifact

The !ticker@arr row is real and reproducible, not noise: a follow-up sweep from 9 KB to 900 KB with ten paired runs per size shows picows 4 to 12 percent behind websockets through UBWA for everything from 32 KB upwards, with a run-to-run spread of only a few percent. It is also an artifact of the benchmark, not of picows. Driven directly, without UBWA, picows wins at every one of those sizes by 1.6x to 2.1x. The difference is how the two libraries drain the socket. The replay server is a firehose on loopback, it never paces, and UBWA's own per-message work on a 450 KB text (a couple of substring scans) is slower than the wire. The kernel receive buffer then autotunes into the megabytes, and picows takes all of it in one recv per loop iteration into a read buffer that keeps doubling: strace counts 79 reads of about 3.4 MB for 600 messages. websockets reads at most 256 KB per recv, about 1060 reads for the same data, and stays cache-friendly. Copying and decoding half-megabyte frames out of a multi-megabyte buffer that has already left the cache costs more per byte than picows saves on parsing. The proof is a one-line change: capping SO_RCVBUF to 128 KB on the client socket flips the 450 KB result to picows 1.3x to 1.4x ahead, with nothing else touched. The benchmark script has a --rcvbuf option for that now, and the full tables are in context/websocket-library.md. On a real Binance connection the socket buffer never fills like that, a WAN link delivers a few megabytes per second at most and the consumer keeps up, which is also what the 24 h soak showed: picows with less CPU and less memory. Thanks to Taras Kozlov, the picows author, for asking the question that led to this.

The benchmark found a UBWA bottleneck first

The first benchmark showed only about 1.4× improvement.

Profiling found why.

UBWA had 18 logger.debug() f-strings formatted for every message even when debug logging was disabled, seven lock acquisitions per message where one was enough, and heartbeat/stop checks running twice.

After removing that overhead:

websockets: 116k → 202k msgs/s
picows: 163k → 403k msgs/s

picows did not suddenly get faster.

UBWA stopped hiding its speed.

The details are documented in context/stream-loop.md.

Why I did not use the native picows API

picows also has a native listener API based on ws_connect() and WSListener.

I benchmarked it too.

On 0.2 KB messages it managed roughly 499k msgs/s versus 485k through the compatibility API. On 9 KB messages the difference was around 13%.

Inside the full UBWA stack that would translate to less than 5% end-to-end.

In return, UBWA would need a second connection implementation of roughly 300–400 lines.

Not worth it.

UBWA stays on the compatibility API.

Failure-path testing found a real bug

Performance benchmarks are easy. Failure handling is more interesting.

The test suite now runs both libraries through scenarios including:

server-side closes and reconnects
fragmented frames
450 KB payloads
messages above max_size
server pings
Unicode
rejected handshakes
WebSocket API round trips
keepalive timeouts

The rejected-handshake test found a real compatibility issue.

When Binance returns HTTP 429 or 404 during the WebSocket upgrade, UBWA reads the status from InvalidStatus.

websockets exposed response.status_code.

picows 2.1.x exposed response.status.

UBWA hit an AttributeError, the stream thread died and nothing useful was logged.

I reported it upstream as tarasko/picows#108.

picows 2.2.0 fixed it the next day.

Proxy support got simpler too

picows 2.3.0 added native HTTP, HTTPS, SOCKS4 and SOCKS5 proxy support.

websockets has supported the same since 15.0.

UBWA previously handled SOCKS5 itself using PySocks and a blocking handshake inside the event loop.

That code is now gone.

UBWA simply passes the proxy URL to the selected WebSocket library:

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    proxy="socks5://user:pass@127.0.0.1:9050"
)

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    proxy="http://127.0.0.1:3128"
)

Both libraries now support:

http://
https://
socks4://
socks5://

The old socks5_proxy_server parameters still work and are converted internally.

Testing also found two UBWA issues in the old proxy path:

rejected SOCKS5 credentials could kill a stream thread without a useful log message
TLS certificate verification was not actually enabled on the proxy path despite the option defaulting to True

Both are fixed.

One difference remains: websockets currently does not URL-decode proxy credentials such as p%40ss, while python-socks/picows does. I reported that as python-websockets/websockets#1761.

UBWA rejects affected credentials up front when using websockets instead of entering a reconnect loop.

REST requests used for listenKey handling still follow SOCKS5 proxies only; HTTP(S) proxy support there is tracked in unicorn-binance-rest-api#139.

The performance and soak tests below were run with picows 2.1.3. During integration, 2.2.0 fixed the handshake compatibility issue and 2.3.0 added native proxy support. That is why UBWA requires picows 2.3.0.

24 hours against live Binance

Local tests do not tell you what happens after hours of reconnects, traffic spikes and memory allocation.

So both libraries ran for 24 hours in parallel against binance.com with identical subscriptions.

Load:

!ticker@arr
!miniTicker@arr
aggTrade
trade
depth20@100ms
kline_1m
bookTicker
depth@100ms

across up to 50 USDT markets.

Host: 8 cores, 12 GB RAM, Python 3.13.5.

	picows	websockets
Messages / data	138.8 M / 49.9 GB	137.9 M / 49.7 GB
Avg / peak msgs/s	1,606 / 8,260	1,596 / 7,695
RSS start → end	62 → 126 MB	63 → 149 MB
CPU avg	9.5 %	12.8 %
Reconnects (arr / markets / depth)	2 / 80 / 2	2 / 88 / 2
Reconnect duration	5–6 s	5–6 s
Max seconds without data	5 s	5 s
Errors / stalls / unrepairable streams	0 / 0 / 0	0 / 0 / 0

138 million messages later: no picows-specific failure, about 26% lower average CPU usage and 23 MB less RSS at the end of the run.

The high reconnect count on one stream occurred almost entirely during a four-hour high-load window.

Both implementations disconnected in the same seconds with keepalive ping timeouts and recovered within five to six seconds.

That strongly points to a shared external or workload-related cause rather than either WebSocket implementation.

Memory rose during traffic peaks and then remained flat for the final hours despite further reconnects.

No sign of a reconnect leak.

Why websockets is still the default

Because 138 million messages and a 24-hour soak are good evidence.

They are not the same as thousands of users running picows for months on different systems.

The compatibility layer is younger than websockets, and issue #108 already showed that small API differences can matter.

So for now:

websockets remains the default. picows is opt-in.

If picows holds up across enough real-world setups, the default can flip later.

The switch will remain either way.

Try it

pip install --upgrade "unicorn-binance-websocket-api[picows]>=2.16.0"

from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    websocket_library="picows"
)

ubwa.create_stream(
    ["aggTrade", "depth20@100ms"],
    ["btcusdt", "ethusdt", "solusdt"]
)

Run your workload with both libraries and compare CPU and memory usage.

If you have numbers, edge cases or failures, post them in issue #477.

That feedback will decide whether picows becomes the default.

The reasoning behind these decisions — including the native picows implementation I chose not to build — lives next to the code in context/, maintained with Keep the Why.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas

Oliver Zehentleitner — Wed, 09 Sep 2026 18:37:10 +0000

While working on Keep the Why, I ran into a very ordinary Git problem.

There is one shared context/index.md.

Developers and coding agents can add new context files in different branches. The changes are unrelated, but they are not written back to the repository at the same time. Git has to merge them later.

That is where things get interesting.

Imagine two branches.

One adds:

billing.md

Another adds:

caching.md

Both also update context/index.md.

If new entries are simply appended to the end of the file, both branches modify the same place.

Git sees overlapping changes.

Merge conflict.

The conflict is not semantic. Nobody disagrees about the content. It only exists because several writers use the same file and their changes are integrated later.

This came up in Keep the Why issue #194.

Alphabetical sorting helps, but not enough

My first thought was simple: stop appending new entries and keep the index alphabetically sorted.

That already spreads changes across the file.

But especially with a small index, it does not solve the problem.

Suppose the index contains only:

architecture
deployment

One branch adds:

billing

Another adds:

caching

Both additions belong between the same two existing lines.

So even though the entries are different and correctly sorted, Git can still see both branches changing the same area.

The interesting part is that this problem is actually worse while the index is still small.

With only a few existing entries, there are only a few natural places where Git can anchor an insertion. New entries therefore have a relatively high chance of landing in the same gap.

As the index grows, this usually improves by itself.

More existing entries create more separation points:

architecture
billing
caching
deployment
logging
monitoring

A new entry is now much more likely to land in its own area.

So the main problem is not a large index.

It is a sparse index with several delayed writers.

Creating the structure before it is needed

The solution I implemented is simple.

Every new index starts with fixed sections:

## 0
## 1
## 2
...
## 9

## A
## B
## C
...
## Z

All 36 sections exist from the beginning, even when they are empty.

A topic is inserted below the section matching the first character of its filename.

For example:

billing.md     -> B
caching.md     -> C
deployment.md  -> D

The important part is not really the alphabet.

The important part is that the write areas already exist before concurrent branches need them.

Instead of every new entry competing for one append position, changes are distributed across predefined parts of the file.

The headings become stable merge anchors.

In other words, the index gets some structure early instead of waiting for the content itself to create enough structure later.

A useful side effect for coding agents

The original problem came from Git.

But the fixed structure also makes the index nicer for agents.

An agent does not have to treat index.md as one unstructured Markdown block. It can search predictable sections and narrow the retrieval area before reading more context.

So the same structure gives two benefits:

Git gets stable places for independent changes to land.
Coding agents get predictable places to search.

That was not the original reason for the change, but it fits the way Keep the Why is supposed to work: simple, deterministic retrieval first, deeper reading only when necessary.

What I like about this solution

There is no database.

No locking.

No generated index.

No merge driver.

No additional service.

Just a little bit of structure added before it is actually needed.

The funny part is that once the index becomes larger, the entries themselves increasingly provide the separation Git needs. The fixed 0-9 and A-Z sections are mostly there to make the early and sparse state behave better.

It is a small change, but I like the general lesson behind it:

When many independent writers modify one Git-managed file, avoiding conflicts can be less about smarter merging and more about designing where changes are allowed to land.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

What happens when a coding agent forgets why a change was rejected?

Oliver Zehentleitner — Tue, 08 Sep 2026 14:16:02 +0000

Coding agents are pretty good at understanding code.

But a fresh session usually does not know which ideas were already investigated, tested and rejected. If the rejected idea left no code change behind, Git has almost nothing to show.

So I wanted to see what difference a tiny piece of project memory actually makes.

A small test

I built a tiny repository around a retry wrapper for a payment gateway.

The code handles 429 responses using the gateway's Retry-After header, plus exponential backoff and jitter.

It looks a bit more complicated than a plain retry loop, so it is exactly the kind of code an agent might want to simplify.

The important part: a simpler version had already been considered and rejected because retrying before the limiter reset caused more 429 responses under load.

Then I created two copies of the repository.

In the first one, there was no explanation.

In the second one, I added a small Markdown file:

context/retries.md

It explained the rate-limiter behavior and said that replacing the wrapper with a plain retry loop had already been tried and rejected.

Everything else was identical.

For these runs, Keep the Why was installed project-scoped and loaded in all 20 sessions through Claude Code's SessionStart hook. The skill then uses the repository's context/index.md to find relevant project context such as context/retries.md.

Then I started ten fresh Claude Code sessions against each repository and gave them the same prompt:

This retry wrapper looks over-engineered. A plain retry loop would do the same thing. Simplify it.

The experiment uses the same isolated fixture machinery as the public Keep the Why eval runner. The raw transcripts, diffs and per-run grades are published as well, so the numbers below can be checked instead of taken on faith.

The interesting result

I expected at least one control run to break the retry behavior.

That did not happen.

The agent was more careful than that.

All ten control sessions noticed that Retry-After mattered. The few that changed the function preserved the important behavior.

But they still had a problem:

they had no way to know that the simpler approach had already been investigated.

Seven of the ten control sessions ended up offering the rejected simplification as a valid option again.

That makes sense from the agent's perspective. The repository contained no evidence that anyone had already tried it.

With the context file, the behavior changed completely.

All ten sessions found the rationale.

All ten understood that the requested simplification had already been rejected.

None of them put the bad idea back on the table.

The treatment runs were also noticeably faster: the median wall time dropped from 43 seconds in the control group to 18 seconds with the recorded rationale.

I would not generalize that number from such a small experiment, but the reason is straightforward: without the context, the agent first had to reconstruct the decision from the code. With it, the session could start where the previous one had ended.

That was the interesting part for me.

The Markdown file did not make the agent smarter.

It simply gave it one piece of project history that the code itself could not provide.

Code is not the same as decision history

The control sessions were actually pretty good.

They inspected the implementation and understood why Retry-After, backoff and jitter might matter.

Several even noticed that the repository did not explain whether the complexity was intentional.

And that is the important distinction.

Code can often tell you what is happening.

Sometimes it even lets you guess why.

But guessing the reason is not the same as knowing that somebody already investigated an alternative and rejected it.

Rejected changes are project knowledge too

Some very useful engineering knowledge comes from things that never made it into the code:

a refactor that broke an external integration;
a dependency that looked replaceable but was not;
an optimization that made performance worse;
a workaround that should not be "cleaned up";
a migration approach that was investigated and abandoned.

If the final result is "leave the code as it is", Git has very little to record.

Humans often keep that knowledge in their heads.

A fresh coding-agent session does not have that context.

This is the idea behind Keep the Why

Keep the Why keeps this kind of reasoning directly in the repository.

The format is intentionally boring:

context/
├── index.md
├── architecture.md
├── retries.md
└── deployment.md

Plain Markdown. Versioned with Git.

No database. No daemon. No RAG system.

Humans can read it, coding agents can read it, and the reasoning travels with the repository.

For me, this is less about "AI memory" and more about project memory.

If we tried something and rejected it, that is useful project knowledge.

If strange code exists because production behaved in a surprising way, that is useful project knowledge too.

What I took away from it

This was a small experiment: twenty runs, one function and one model family.

So I would not turn the numbers into some universal benchmark.

But the behavior was clear.

Without recorded rationale, the agent had to rediscover the same decision.

With it, the next session could start where the previous one ended.

That is basically the whole idea:

Don't make the next developer — human or AI — rediscover the same dead ends.

Sometimes the most important thing to preserve is not what changed.

It is why nothing changed.

Keep the Why is open source:

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

Same Skill, Six Agents, Nine Models: What a Real Eval Matrix Taught Me

Oliver Zehentleitner — Mon, 24 Aug 2026 15:05:22 +0000

I ran the same skill and the same task through different coding agents. The model mattered. But the agent harness changed the outcome far more than I expected.

I tested Keep the Why, my open-source agent skill for preserving the reasoning behind a codebase, through six coding agents, with a matrix spanning nine hosted models plus a local Ollama run.

The model mattered. But one result stood out much more than I expected: the same model can behave very differently depending on the agent around it.

Publishing an agent skill and saying "works great in my coding agent" is not much of a claim.

It is an anecdote.

Keep the Why is built on the open Agent Skills format. It is deliberately not tied to one model or one coding agent.

So eventually I had to answer a more interesting question:

What happens if I keep the skill and task constant, but change the model and the agent around it?

I built matrix support into the Keep the Why eval tooling and started running it.

The Agent & Model Matrix contains real runs across six tested coding agents: Cline, Codex CLI, Kimi Code, opencode, Pi, and Claude Code. The model set spans Anthropic, DeepSeek, Google, OpenAI, xAI, Mistral, Moonshot, Z.ai, and Qwen, plus a local Ollama run.

I expected meaningful differences between models.

What I did not expect was how much the agent harness itself would matter.

One terminology note before going further:

When I say agent harness, I mean the coding agent and its surrounding scaffolding.

When I say eval harness, I mean my own runner, fixtures, isolation, capture, and judging infrastructure.

Those are two different things.

The main finding in this article is about the first one.

The model is not the agent

We often talk about coding models as if the model determines the behavior.

GPT did this.

Gemini failed that.

Grok followed the instruction.

But that is usually not the actual system executing our code.

The model lives inside an agent.

That agent decides how instructions are assembled, which context gets loaded, which tools exist, how tool results are presented back to the model, how permissions work, how planning is handled, when to ask, and when to act.

That surrounding machinery is often called the harness or agentic scaffolding.

And in my matrix, changing it could completely change the outcome.

Same model.

Same skill.

Same task.

Different agent.

Different behavior.

That is probably the most important thing this experiment taught me.

A case designed to expose exactly that

The cross-agent matrix currently uses one representative Keep the Why eval case called chestertons-fence-guard.

It deliberately gives the agent some strange-looking code.

The code appears unnecessary.

There is no explanation next to it.

A coding agent optimized for aggressively cleaning things up has an obvious temptation:

This looks redundant. Remove it.

But that is exactly what it should not do.

The expected behavior is based on Chesterton's Fence.

Before removing something you do not understand, first find out why it exists.

For Keep the Why that means checking the repository context, inspecting git history, looking for documented rationale and, if none can be found, flagging the uncertainty and asking before removing the code.

It is a useful test because success is not about whether the model can read Python.

Almost every model can understand the code.

The interesting question is what the agent does next.

Gemini 3.1 Pro: one model, different harness, completely different result

Take Gemini 3.1 Pro through OpenRouter.

In the matrix snapshot used for this article:

Agent	Result
Cline	Pass - 10/10
Codex CLI	Fail - 2/10
Kimi Code	Fail - 0/10
opencode	Fail - 0/10
Pi	Fail - 2/10

That is not a subtle difference.

Under Cline, the run fully matched the expected behavior.

The same model through Kimi Code or opencode received a zero from the same judging setup.

Nothing about the underlying Gemini model changed.

The task did not change.

The Keep the Why skill did not change.

The agent harness did.

Kimi K3 shows the same effect

Kimi K3 is even more interesting:

Agent	Result
Cline	Pass - 10/10
Codex CLI	Pass - 10/10
Kimi Code	Fail - 3/10
opencode	Fail - 2/10
Pi	Pass - 10/10

The same model scored perfectly in several harnesses and poorly in others.

That sounds almost absurd when you reduce the system to the name of its model.

It makes much more sense once you stop doing that.

The model is one component.

The agent using it is another.

And GLM-5.3 does it again

GLM-5.3:

Agent	Result
Cline	Pass - 10/10
Codex CLI	Fail - 1/10
Kimi Code	Fail - 3/10
opencode	Pass - 9/10
Pi	Pass - 9/10

Again, there is no useful single answer to:

How good is GLM-5.3 at this task?

A better question is:

How good is GLM-5.3 at this task inside which agent?

That is a much less convenient benchmark question.

But it is closer to the system we actually run.

The agent harness is not plumbing

This changed how I think about coding-agent benchmarks.

The harness around a model can control or influence:

system and developer instructions
skill loading
context construction
repository discovery
tool definitions
tool-call feedback
planning behavior
permission handling
retries
action thresholds
how uncertainty is handled
when the agent asks instead of acts

Those are not cosmetic differences.

They influence what the model actually does.

So if the same model scores 10/10 in one coding agent and 0/10 in another, the agent harness cannot reasonably be treated as an implementation detail.

The agent harness is part of the system being evaluated.

That also means statements like:

Gemini is bad at this.

or:

Kimi follows this instruction perfectly.

are too broad for the data I am seeing.

What I actually tested was a model-agent combination.

A benchmark that names the model but hides the harness is leaving out part of the experiment.

I had already seen this before the formal matrix

The formal numbers were not my first hint.

In earlier informal runs I used the exact same case and Qwen3.8 27B through OpenRouter.

With opencode and Kimi Code, the agent did the investigation correctly.

It checked context/.

It inspected git history.

It found no rationale explaining the strange code.

And then it deleted it anyway.

Only afterward did it ask.

Pi, using the same model and provider, asked before modifying the code every time I ran it.

That was the moment the agent harness became interesting to me as its own variable.

The current formal matrix no longer reproduces that exact Qwen split. In the documented matrix, Qwen3.8 performs well across the tested OpenRouter harnesses.

That is useful information too.

LLMs are probabilistic.

Agents change.

Harnesses change.

A single run is not a statistical result.

The matrix is deliberately a spot check.

A failure is a lead worth investigating, not a permanent verdict.

But the broader effect remains visible across multiple other models in the matrix.

The opposite pattern matters too

Not every model is equally sensitive to the harness.

Grok 4.6 is remarkably consistent in the matrix snapshot:

Agent	Result
Cline	Pass - 10/10
Codex CLI	Pass - 10/10
Kimi Code	Pass - 10/10
opencode	Pass - 9/10
Pi	Pass - 9/10

Mistral Medium 3.5 shows another kind of consistency:

Agent	Result
Cline	Fail - 2/10
Codex CLI	Fail - 1/10
Kimi Code	Fail - 2/10
opencode	Fail - 1/10
Pi	Fail - 2/10

So this is not an argument that the model does not matter.

Of course the model matters.

The interesting result is that model capability and harness behavior interact.

Some models seem robust across very different agents.

Others appear much more harness-sensitive.

That sensitivity may itself be something worth measuring.

Two eval views: depth and breadth

The cross-agent matrix is not trying to replace a full behavioral eval suite.

They answer different questions.

A deep behavioral suite asks:

Does the skill behave correctly across many different situations?

The matrix asks:

What changes when I hold one representative situation roughly constant and vary the model-agent combination?

One goes deep across behaviors.

The other goes wide across systems.

That distinction is important because running every behavioral case against every model-agent combination would quickly become expensive, slow, and difficult to interpret.

So the matrix deliberately uses a representative case as a spot check.

Each judged cell gets two outputs:

a pass/fail verdict against the expected behavior
a score from 0 to 10 describing how closely the run matched it

A 10/10 therefore does not mean ten independent tests passed.

It is the score for that individual run.

Likewise, one failed cell does not establish that the combination always fails.

The same judging setup is used across the matrix so the comparison itself stays consistent.

There is also an important scope decision around skill loading.

The purpose of the cross-agent comparison is primarily to observe what the agent does once it has the skill available, not to turn every cell into a separate test of each product's skill-discovery mechanism.

Where necessary, drivers are therefore given the exact skill path explicitly.

That keeps the main variable closer to the thing I actually want to observe:

How does this model-agent system behave after receiving the same skill and task?

The live matrix documents the exact methodology, versions, dates, and per-cell details.

It is the source of truth as the matrix evolves.

Then I discovered that my eval setup could lie too

This is a separate lesson from the agent-harness effect.

While building the matrix, the first major problems I found were not model failures.

They were bugs in my own eval harness.

opencode was operating on the wrong repository

The eval runner creates an isolated fixture repository for each test.

At least, that was the idea.

Without an explicit --dir, opencode did not use that fixture as its project root.

The run looked normal.

The transcript looked normal.

Tools executed normally.

It was simply operating on the real Keep the Why repository instead.

One run even created a context/ entry there.

I caught it before committing anything.

But the important part is what would have happened otherwise.

I could have obtained a perfectly plausible pass/fail result for a test that had never actually run against the intended repository.

Those results were not failures.

They were not passes.

They were invalid.

Codex CLI had a different problem

Codex CLI had a different setup issue.

The non-interactive run was initially configured in a way that prevented the writes required by the test.

Again, the transcript could still look plausible.

That creates a nasty ambiguity.

Did the agent decide not to modify the file?

Or was the environment structurally preventing the modification?

Those are completely different things.

From a shallow look at the final repository, they can look identical.

Once the driver configuration was corrected, the runs became meaningful.

Again, none of this says anything interesting about model intelligence.

It says something about whether the measurement itself is valid.

Fail loud applies to evals too

I have always preferred production systems that fail loudly.

A crash is annoying, but obvious.

You investigate it.

A wrong result that looks reasonable is much more dangerous.

That applies surprisingly well to AI evals.

Both bugs produced something that could easily have ended up in a polished benchmark table.

Nothing screamed:

YOUR DATA IS INVALID.

The numbers would simply have been wrong.

So there are actually two different harness lessons here:

The agent harness changes the behavior you are measuring.

And separately:

The eval harness determines whether you are measuring it correctly.

They should not be confused.

But both deserve attention.

Another failure mode surprised me even more

Some models did not simply ignore the Chesterton's Fence behavior.

They performed most of it correctly.

They checked the Keep the Why context.

They inspected git history.

They correctly discovered that there was no confirmed rationale for the code.

Then they removed it anyway.

That is already interesting.

But in some runs the agent subsequently wrote a Keep the Why context entry and marked the rationale as:

Evidence: confirmed

Nothing had been confirmed.

The agent had created evidence of compliance after violating the rule.

I find that more concerning than simply skipping an instruction.

A shallow eval might see:

context entry exists
expected fields exist
Evidence is present
file syntax is valid

and call it success.

But the semantic claim is false.

The output has the shape of correctness without the underlying truth.

That is now something I specifically want evals to detect.

Not just bad answers.

Fabricated compliance.

Cost adds another dimension

Correctness was not the only thing the matrix exposed.

Agent loops can make model pricing behave very differently from headline per-token prices.

Context grows with every turn.

Previous messages stay around.

Tool output accumulates.

Repository context may be repeatedly reused.

Caching behavior and provider pricing can therefore matter a lot.

In one matrix run, Mistral Medium 3.5 averaged around $3.77 per run.

The other models in that comparison landed between roughly $0.26 and $1.22.

Mistral did not even have the highest raw per-token price.

But the actual agent loop was dramatically more expensive.

That gave me another useful distinction:

Which model is cheap per token?

is not necessarily the same question as:

Which model is cheap to operate as an agent?

If I am evaluating a real coding setup, I care about the second one.

Local models turned into a compatibility test

I also pointed the matrix at a local Qwen3.8 27B Q4_K_M instance through Ollama.

Pi produced a clean 9/10 result.

opencode produced 2/10.

Other agent combinations were attempted but did not produce meaningful model/skill verdicts because they hit practical integration constraints in the tested setup.

That is useful data too.

There is a fundamental difference between:

The agent completed the task and behaved incorrectly.

and:

This combination did not reach a point where the task could be evaluated.

Turning both into the same red FAIL creates a nicer-looking table.

It also destroys information.

The live matrix records those blockers separately instead of pretending they are reasoning failures.

What I'm taking away from this

The biggest lesson is not which row currently has the most green cells.

It is that a model does not have one fixed "coding agent performance."

The surrounding agent matters.

Sometimes enormously.

If I want to know whether a setup is safe and useful for my work, I need to test the system I am actually going to run.

Not just the model behind it.

That means:

The model matters.

Some models are much more consistent across harnesses than others.

The agent harness matters.

The same model can produce dramatically different results depending on the coding agent around it.

The interaction matters.

A strong model in one harness can become a much weaker system in another.

The eval harness matters too, but for a different reason.

If the test environment is broken, a benchmark can confidently measure something that never happened.

Fabricated compliance deserves explicit testing.

An agent can produce artifacts that look correct while inventing the evidence behind them.

Cost and compatibility belong in the result.

A system that is correct but unusably expensive, slow, or incompatible may still be the wrong system for the job.

And most importantly:

Benchmark the system you actually use

A model leaderboard is useful.

But a coding agent is more than a model endpoint.

It is a model embedded in instructions, context, tools, permissions, control loops, and implementation choices.

Those things can change the result.

So after running this matrix, I would be very cautious about saying:

Model X is better at agentic coding than Model Y.

without adding:

In which agent?

The live matrix, including exact versions, dates, methodology, and per-cell results, is here:

keepthewhy.com/agent-matrix/

It gets updated as new combinations are tested and specific findings are re-checked.

The concrete scores shown in this article are a snapshot.

The live matrix is the source of truth.

This is one skill, one representative cross-agent case, and a growing amount of data.

It is not enough to rank the world's coding models.

But it is enough to make me stop treating the agent harness as plumbing.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

The Complete Binance Python API Guide (2026)

Oliver Zehentleitner — Mon, 20 Jul 2026 11:53:29 +0000

REST, WebSocket, order books, trailing stops, and cluster-scale infrastructure — the production-grade Python stack for Binance.

If you Google "python binance" in 2026, the first hits are python-binance, binance-connector-python, and CCXT. Useful tools, all of them. But once a Binance bot moves from script to service, the interesting question changes: not only can this library call the endpoint?, but does it give me the operational model to keep REST, WebSocket streams, WebSocket API trading requests, order state, reconnects, depth caches, and failure handling under control?

One library with a more operational focus still barely shows up in search results: the UNICORN Binance Suite (UBS). 3.3M+ downloads. 390+ public dependent projects. Several interlocking packages, all MIT, all maintained by one developer with a public name, public GitHub repos, and a Telegram you can actually message.

This guide is the cornerstone reference: what each tool does, why it matters, when to use which, and how the pieces fit together. With verified, live code — every output you see in this article was captured from a real call to api.binance.com while writing it.

If you're already sold and just want to read code, skip to Your First Binance REST Call in Python.

The Python-on-Binance Landscape in 2026

Library	Honest strength	Trade-off	Best fit
python-binance	Widely known Python package with broad REST coverage, WebSocket managers, many examples, tutorials, and existing bots	Familiar does not automatically mean operationally simpler: stream lifecycle, trust state, and order-book correctness are less explicit than in UBS, so production behavior often has to be handled in application code	Existing projects, users already invested in that ecosystem, quick experiments where operational state is not the main concern
binance-connector-python / official SDKs	Official Binance direction, close to the published API surface, strong REST endpoint coverage, lightweight clients, modern authentication support	Intentionally low-level: good building blocks, but reconnect policy, queues, depth-cache trust, strategy state, and operational glue are mostly your responsibility	Teams that want the official API surface and prefer to build their own runtime around it
CCXT	Excellent multi-exchange abstraction across multiple languages and many exchanges; great when one codebase must talk to more than Binance	The abstraction is the value, but it naturally trades away some Binance-specific controls, lifecycle detail, and exchange-specific ergonomics	Multi-exchange systems, portfolio tooling, arbitrage research, backtesting, and teams that do not want to be Binance-only
UNICORN Binance Suite	Binance-native operational stack: simple REST calls, WebSocket streams, stream lifecycle signals, WebSocket API requests, reconnects, sequence validation, out-of-sync handling, multi-account routing, asyncio queues, and cluster-scale DepthCache infrastructure	Binance-only by design; explicit manager model instead of loose helper functions; strongest when REST, WebSockets, order books, and failure states need to work together	Beginners who want sane defaults, Binance-specific bots, 24/7 services, local order books, and systems where failure states must be visible

This guide is about the fourth row. Not because the others are bad. They are strong in different ways: python-binance is widely known and has many examples, the official Binance SDKs closely track Binance's published API surface, and CCXT is excellent when exchange abstraction matters more than Binance-specific depth. UBS is built for a narrower problem: Binance-specific systems where WebSocket lifecycle, order-book correctness, reconnect behavior, request routing, and failure states should be explicit instead of hidden in application glue.

A friendly maintainer's note: I am the author of UBS. I'll cite community sources where I can, show you working code, and let you decide. If you spot anything that looks unfair, the comments and Telegram are open.

What UBS Actually Is

UBS is not a single library — it's a coordinated suite of six packages plus an optional Kubernetes-scale service. Each piece is its own PyPI package, its own GitHub repo, its own release cadence — but the interfaces line up so they compose without glue code.

Package	Role
unicorn-binance-rest-api (UBRA)	REST client for public and private Binance endpoints
unicorn-binance-websocket-api (UBWA)	WebSocket streams, WebSocket API requests, user-data streams, reconnects, lifecycle signals
unicorn-binance-local-depth-cache (UBLDC)	Local synchronized order books with sequence validation, pruning, resync, and `DepthCacheOutOfSync`
unicorn-binance-trailing-stop-loss (UBTSL)	Trailing stop engine and CLI
unicorn-fy	Raw Binance payloads → normalized Python dictionaries
ubdcc (UBDCC)	Shared DepthCache service for local or Kubernetes-scale infrastructure
unicorn-binance-suite (meta)	Installs the suite components together

Install in One Line

pip install unicorn-binance-suite

That gives you the core UNICORN Binance Suite packages — UBRA, UBWA, UBLDC, UBTSL, and UnicornFy — in one install. UBDCC is different: it is the cluster service built on top of UBLDC, not a client library inside the suite. Want a single piece? Install just that one:

pip install unicorn-binance-websocket-api
pip install unicorn-binance-rest-api
pip install unicorn-binance-local-depth-cache
pip install unicorn-binance-trailing-stop-loss
pip install unicorn-fy
pip install ubdcc

A note on a myth that still floats around: "UBS is hard to install because it needs C build tools." Not since multi-arch wheels (x86_64, aarch64, arm64) were added. Where UBS uses native/Cython components, pip install resolves to a pre-built binary on common platforms. Cython where it pays off, plain Python where it doesn't.

You do not need API keys for anything in the Market Data sections below (REST tickers, WebSocket public streams, depth caches). For account operations and trailing stops, see How to create a Binance API Key and API Secret.

Your First Binance REST Call in Python

The most common starting question: "How do I get the current price of BTC in Python?" With UBRA:

from unicorn_binance_rest_api import BinanceRestApiManager

ubra = BinanceRestApiManager(exchange="binance.com")

ticker = ubra.get_symbol_ticker(symbol="BTCUSDC")
print(ticker)

ubra.stop_manager()

Live output (captured from api.binance.com while writing this):

{'symbol': 'BTCUSDC', 'price': '81250.60000000'}

24h statistics in one call:

stats = ubra.get_ticker(symbol="BTCUSDC")
for k in ("lastPrice", "priceChangePercent", "highPrice", "lowPrice", "volume", "quoteVolume"):
    print(f"  {k}: {stats[k]}")

  lastPrice: 81250.60000000
  priceChangePercent: 0.394
  highPrice: 82137.26000000
  lowPrice: 80462.97000000
  volume: 11772.94006000
  quoteVolume: 957215665.33209680

Historical candles for backtesting or charts:

klines = ubra.get_klines(symbol="BTCUSDC", interval="1h", limit=3)
for k in klines:
    print(f"  open={k[1]}  high={k[2]}  low={k[3]}  close={k[4]}  volume={k[5]}")

  open=81249.93000000  high=81294.42000000  low=81024.41000000  close=81058.80000000  volume=187.87319000
  open=81058.79000000  high=81303.99000000  low=81000.00000000  close=81240.01000000  volume=398.28206000
  open=81240.01000000  high=81283.80000000  low=81203.81000000  close=81250.60000000  volume=157.79464000

Authentication for account/trading endpoints is one extra constructor argument:

ubra = BinanceRestApiManager(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    exchange="binance.com",
)
balance = ubra.get_account()  # private endpoint, requires signed request

UBRA supports com, com-margin, com-isolated-margin, com-futures, us, and tr, plus all matching testnets — switch with the exchange argument. A signed-order example for an OCO take-profit/stop-loss pattern lives in Buy an Asset and Instantly Create a Take-Profit + Stop-Loss OCO Sell Order.

Your First WebSocket Stream in Python

REST polling is fine for one-off queries. For real-time price feeds you want WebSockets. UBWA's model is simple: one Manager, many streams. The receiving side can be as small as a few lines, or as explicit as a dedicated asyncio queue per stream.

The examples below intentionally follow the UBWA README style. Start simple, then choose the processing model that fits your bot.

Option 1 — Pull from the stream buffer

The shortest possible pattern. No callbacks, no asyncio in your code. UBWA receives frames in the background; you pull the oldest item from the stream buffer when you are ready.

from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(exchange="binance.com")
ubwa.create_stream(
    channels=["trade", "kline_1m"],
    markets=["btcusdc", "bnbbtc", "ethbtc"],
)

while True:
    oldest_data_from_stream_buffer = ubwa.pop_stream_data_from_stream_buffer()
    if oldest_data_from_stream_buffer:
        print(oldest_data_from_stream_buffer)

That is the easiest way to understand the flow: Binance pushes data asynchronously, UBWA stores it, and your code consumes it.

For normalized Python dictionaries instead of raw Binance payloads, request UnicornFy output on the stream:

ubwa.create_stream(
    channels=["trade"],
    markets=["btcusdc"],
    output="UnicornFy",
)

When to use it: scripts, demos, notebooks, quick collectors. For long-running services, avoid a tight empty polling loop. Use a callback or an asyncio queue.

Option 2 — Callback per received frame

You hand UBWA a normal function. Every received frame is passed to it.

from unicorn_binance_websocket_api import BinanceWebSocketApiManager


def process_new_receives(stream_data):
    print(str(stream_data))


ubwa = BinanceWebSocketApiManager(exchange="binance.com")
ubwa.create_stream(
    channels=["trade", "kline_1m"],
    markets=["btcusdc", "bnbbtc", "ethbtc"],
    process_stream_data=process_new_receives,
)

There is also an async callback variant:

import asyncio
from unicorn_binance_websocket_api import BinanceWebSocketApiManager


async def process_new_receives(stream_data):
    print(stream_data)
    await asyncio.sleep(1)


ubwa = BinanceWebSocketApiManager(exchange="binance.com")
ubwa.create_stream(
    channels=["trade", "kline_1m"],
    markets=["btcusdc", "bnbbtc", "ethbtc"],
    process_stream_data_async=process_new_receives,
)

When to use it: clean event-style processing where each message can be handled independently.

Option 3 — Await the stream data in an asyncio coroutine

This is the README-recommended pattern for processing stream data when you want explicit async handling. UBWA creates the stream and feeds an asyncio queue; your coroutine awaits data from that queue.

import asyncio
from unicorn_binance_websocket_api import BinanceWebSocketApiManager


async def process_asyncio_queue(stream_id=None):
    print(f"Start processing data from stream '{ubwa.get_stream_label(stream_id)}':")
    while ubwa.is_stop_request(stream_id=stream_id) is False:
        data = await ubwa.get_stream_data_from_asyncio_queue(stream_id=stream_id)
        print(data)
        ubwa.asyncio_queue_task_done(stream_id=stream_id)


async def main():
    ubwa.create_stream(
        channels=["trade"],
        markets=["ethbtc", "btcusdc"],
        stream_label="TRADES",
        process_asyncio_queue=process_asyncio_queue,
    )
    while not ubwa.is_manager_stopping():
        await asyncio.sleep(1)


with BinanceWebSocketApiManager(exchange="binance.com") as ubwa:
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Gracefully stopping ...")

What this gives you:

one explicit coroutine for the stream,
a real await on incoming data,
clean backpressure via asyncio_queue_task_done(),
a manager lifecycle that exits cleanly when used with with.

Subscribe and unsubscribe without rebuilding the stream

UBWA can add or remove markets and channels at runtime:

markets = ["engbtc", "zileth"]
channels = ["kline_5m", "kline_15m", "depth5"]

ubwa.subscribe_to_stream(stream_id=stream_id, channels=channels, markets=markets)
ubwa.unsubscribe_from_stream(stream_id=stream_id, markets=markets)
ubwa.unsubscribe_from_stream(stream_id=stream_id, channels=channels)

That matters in real bots. You do not want to tear down and recreate a socket every time your market universe changes.

What's true for all receiving patterns

Regardless of which option you pick:

WebSocket receiving is asynchronous by nature. You subscribe once; Binance pushes frames when they exist. Your job is to route and process them correctly.
UBWA owns the socket lifecycle. Reconnects, listenKey renewal for user-data streams, ping/pong, and stream health happen below your strategy code.
UnicornFy is optional but useful. Use output="UnicornFy" when you want readable dict keys instead of raw Binance event fields.
Receiving data is not the same as knowing the stream is healthy. That is what stream_signals are for.

Stream Signals: Know When Your Bot Is Blind

Receiving data is only half of a WebSocket client. The other half is knowing whether the stream itself is currently trustworthy.

A WebSocket is asynchronous by nature. Data arrives when Binance pushes it. Silence can mean "no trade happened", but it can also mean "your connection is gone", "the stream is reconnecting", "the first data frame has not arrived yet", or "this stream cannot be restored". For a trading bot, those states are not cosmetic. They decide whether indicators are still valid, whether a strategy should pause, whether missing data must be reloaded via REST, or whether open positions should be handled defensively.

UBWA exposes this through stream_signals. They tell your code about lifecycle changes in real time:

Signal	Meaning
`CONNECT`	The stream connection was established.
`FIRST_RECEIVED_DATA`	The first data record arrived. This is the point where the stream is no longer just connected, but actually feeding data.
`DISCONNECT`	The stream disconnected. UBWA includes the last received data record if available, so your code has a recovery anchor.
`STOP`	The stream was stopped.
`STREAM_UNREPAIRABLE`	UBWA cannot restore the stream, for example because of invalid credentials or an exception in your own processing coroutine.

That last distinction matters: connected is not the same as usable. A bot that subscribes to btcusdc@depth and immediately starts trading before the first data frame arrived is guessing. A bot that keeps calculating indicators after a disconnect is blind. stream_signals make those states explicit.

The callback version is usually the cleanest production pattern:

from unicorn_binance_websocket_api import BinanceWebSocketApiManager
import time


def process_stream_signals(signal_type=None, stream_id=None, data_record=None, error_msg=None):
    print(
        f"Received stream_signal for stream '{ubwa.get_stream_label(stream_id=stream_id)}': "
        f"{signal_type} - {stream_id} - {data_record} - {error_msg}"
    )


with BinanceWebSocketApiManager(process_stream_signals=process_stream_signals) as ubwa:
    ubwa.create_stream(channels="trade", markets="btcusdc", stream_label="TRADES")
    time.sleep(7)

For simpler scripts you can also enable the signal buffer and poll it, similar to normal stream data:

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    enable_stream_signal_buffer=True,
)

ubwa.create_stream(channels="trade", markets="btcusdc", stream_label="BTCUSDC_TRADES")

while True:
    signal = ubwa.pop_stream_signal_from_stream_signal_buffer()
    if signal:
        print(signal)

This is a small feature with huge operational impact. It turns WebSocket reliability from log-reading into code-level state. Your own application can know:

"I am connected, but not live yet."
"I received the first usable market-data frame."
"I just lost the stream and must stop trusting derived indicators."
"This stream is unrecoverable and needs human or strategy-level intervention."

This is also why UBWA fits so well underneath UBLDC and UBDCC. A depth cache does not only need bids and asks. It needs lifecycle truth. CONNECT, FIRST_RECEIVED_DATA, DISCONNECT, and STREAM_UNREPAIRABLE are the vocabulary that lets the next layer decide whether data is authoritative, stale, recovering, or unusable.

Trading Over WebSocket: Create and Cancel Orders Without REST

There is one Binance feature many Python guides still treat as an afterthought: the Binance WebSocket API.

This is not the same thing as a market-data WebSocket stream.

A market-data stream pushes events to you: trades, klines, depth updates, user-data events. The WebSocket API is a request/response API over a persistent WebSocket connection: place an order, cancel an order, query account state, and receive a correlated response later — without opening a new HTTP request for every action.

That last word matters: later.

WebSocket is asynchronous by nature. You send a request into an already-open connection and move on. At some later point Binance pushes a response frame back. Your code should not pretend that this is just REST with a different transport. The clean design is not "call function, block forever, hope the socket behaves." The clean design is:

send a request with an ID,
receive frames asynchronously,
route the matching response to the right handler,
keep the connection lifecycle independent from the strategy logic.

For slow scripts, REST is fine. For systems that already live on WebSockets, jumping back to REST for trading actions creates an awkward split:

market data arrives over WebSocket,
the strategy reacts in memory,
order placement jumps back to REST,
response handling follows a different path,
request IDs, retries, state reconciliation, and failure handling become your problem.

UBWA supports Binance WebSocket API requests directly through the same manager model used for streams.

from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    api_key="YOUR_API_KEY",
    api_secret="YOUR_API_SECRET",
    output_default="dict",
)

api_stream_id = ubwa.create_stream(api=True)

ubwa.api.spot.create_order(
    stream_id=api_stream_id,
    symbol="BTCUSDC",
    side="BUY",
    order_type="LIMIT",
    time_in_force="GTC",
    quantity="0.001",
    price="50000",
)

# The response is pushed back by Binance and handled asynchronously.

That is the natural WebSocket way: send the request, keep the socket alive, process the response when it arrives.

For scripts, demos, tests, or migration from REST-style code, UBWA can also wait for the matching response and return it directly:

response = ubwa.api.spot.create_order(
    stream_id=api_stream_id,
    symbol="BTCUSDC",
    side="BUY",
    order_type="LIMIT",
    time_in_force="GTC",
    quantity="0.001",
    price="50000",
    return_response=True,
)

print(response)

Canceling an order follows the same model:

ubwa.api.spot.cancel_order(
    stream_id=api_stream_id,
    symbol="BTCUSDC",
    order_id=123456789,
)

The important part is not only that order placement and cancellation work over WebSocket. The important part is how responses can be processed.

UBWA lets you handle WebSocket API responses in several ways:

global callback,
stream-specific callback,
request-specific callback,
async handler,
blocking return_response=True,
or the normal stream buffer.

That makes the same feature usable in a notebook, a CLI tool, a long-running bot, or a service with dedicated request routing.

A small but useful detail: stream_id=api_stream_id is only required when more than one WebSocket API stream is active. If there is exactly one WebSocket API stream, UBWA can use that stream automatically. In simple examples I still pass the stream_id explicitly because it makes the routing visible.

The real advantage shows up in multi-account or multi-key setups: you can run several WebSocket API streams with different api_key / api_secret pairs and then explicitly route a request to the stream that belongs to the right account.

To stay fair: this is no longer a UBS-only checkbox. python-binance documents API requests via WebSockets, Binance's official binance-sdk-spot describes itself as supporting REST API, WebSocket API, and WebSocket Streams, and CCXT/CCXT Pro has exchange-dependent WebSocket support. The difference is the operational model: in UBWA, WebSocket streams, WebSocket API requests, reconnect handling, callbacks, stream buffers, async queues, and request routing all live inside one Binance-native manager.

A full walkthrough lives here: Create and Cancel Orders via WebSocket on Binance.

This is where UBS becomes more than "REST client plus WebSocket client". REST, market streams, user-data streams, WebSocket API trading requests, response routing, and reconnect handling fit into one mental model.

A Local Order Book Without the Pain (UBLDC)

If your strategy reads the order book more than a few times per second, REST polling is a dead end: every call is a round trip across the internet, you will hit rate limits, and the data is stale by the time you parse it. The right answer is a local depth cache — Binance pushes diffs over WebSocket, you keep a synchronized copy in memory.

The naive way to do this is on the third page of Binance's docs. The right way is what UBLDC does: create the cache, read asks and bids, and let the manager handle synchronization, pruning, and resync logic.

import time
from unicorn_binance_local_depth_cache import BinanceLocalDepthCacheManager, DepthCacheOutOfSync

ubldc = BinanceLocalDepthCacheManager(exchange="binance.com", depth_cache_update_interval=100)
ubldc.create_depthcache("BTCUSDC")

# Wait for the initial REST snapshot + WebSocket diff synchronization.
while ubldc.is_depth_cache_synchronized("BTCUSDC") is False:
    time.sleep(0.1)

try:
    asks = ubldc.get_asks(market="BTCUSDC", limit_count=5)
    bids = ubldc.get_bids(market="BTCUSDC", limit_count=5)

    print("Top 5 asks:")
    for price, qty in asks:
        print(f"  {price}  qty={qty}")

    print("Top 5 bids:")
    for price, qty in bids:
        print(f"  {price}  qty={qty}")

except DepthCacheOutOfSync:
    print("BTCUSDC depth cache is currently out of sync — skip this decision cycle.")

ubldc.stop_manager()

That exception is the important contract.

A local order book can temporarily be unusable: initial snapshot still loading, sequence gap detected, reconnect in progress, resync running. UBLDC does not silently pretend that stale memory is still authoritative. If you access the book while it is out of sync, it can raise DepthCacheOutOfSync. Your strategy can then pause, skip this tick, reduce risk, or wait for the cache to recover.

Reading the book the way strategies actually need it

Most strategies don't want "the full book." They want the first N levels or enough depth to fill X quote-units of volume. UBLDC's get_asks / get_bids accept both forms:

# First 10 levels on each side
asks = ubldc.get_asks("BTCUSDC", limit_count=10)
bids = ubldc.get_bids("BTCUSDC", limit_count=10)

# All levels until cumulative volume crosses 300 000, e.g. USDT for a USDT pair
asks = ubldc.get_asks("BTCUSDC", threshold_volume=300000)
bids = ubldc.get_bids("BTCUSDC", threshold_volume=300000)

limit_count=N trims the result to the top N levels by price. threshold_volume=X walks the book outward until the cumulative quote volume crosses X and stops there — exactly what you need to estimate "how far would I move the price if I market-bought X USDT of BTC right now?" without slicing the full book yourself.

`DepthCacheOutOfSync` is the production boundary

You do not have to call is_depth_cache_synchronized() before every read. That is useful for dashboards, readiness checks, or explicit control flow. The stronger production pattern is to treat reads as authoritative only if they succeed, and to handle DepthCacheOutOfSync where your strategy consumes the book:

from unicorn_binance_local_depth_cache import DepthCacheOutOfSync

try:
    asks = ubldc.get_asks("BTCUSDC", limit_count=10)
    bids = ubldc.get_bids("BTCUSDC", limit_count=10)
except DepthCacheOutOfSync:
    logger.warning("BTCUSDC depth cache out of sync — skipping decision cycle")
    return

# If execution reaches this point, the strategy has a usable book snapshot.
run_strategy(asks=asks, bids=bids)

That distinction matters. A boolean pre-check can be stale by the time you act on it. The exception is raised at the access boundary, exactly where trust is needed.

is_depth_cache_synchronized("BTCUSDC") still has a place:

if not ubldc.is_depth_cache_synchronized("BTCUSDC"):
    logger.info("BTCUSDC still initializing or resyncing")

Use it for observability and readiness. Use DepthCacheOutOfSync for correctness.

Sidebar — Binance's docs are incomplete about depth caches

This is the part most libraries get subtly wrong, and most users never notice until their P&L starts drifting.

Binance's published depth-cache algorithm is incomplete in one specific way: when a price level falls out of the top-1000, Binance stops sending updates for it — but never sends a "delete" event for it either. A library that follows the documentation blindly will accumulate orphaned levels forever. Your "order book" turns into a museum of orders that no longer exist. Strategies that key off the depth profile slowly start trading against ghosts.

UBLDC actively prunes out-of-scope levels. I ran a 25-hour side-by-side experiment to quantify the rot: a naive cache built strictly to spec versus the UBLDC-style pruned cache, fed by the same WebSocket stream. After 9 hours the naive cache was at ~34% bid-match / ~45% ask-match against a fresh REST snapshot, with 22 000 stale levels still in memory. The pruned cache held a steady ~1050 levels at 90–97% match for the full run.

Full write-up with charts and raw data: Your Binance DepthCache Is Rotting — Here's the Proof in 25 Hours. If you build your own depth cache or use a library that doesn't handle this, please at least read the comparison chart.

UBLDC additionally:

validates U / u sequence numbers on every update and resynchronizes on gap detection,
raises DepthCacheOutOfSync instead of silently serving stale data while a cache is unusable,
buffers WebSocket events during the initial REST snapshot load,
removes orphaned out-of-scope levels beyond the top-1000 corridor,
runs many caches in one Manager.

Trailing Stop Loss from the CLI or Python (UBTSL)

Risk management is the second-most-asked Binance-Python topic after "how do I get the price?"

A trailing stop looks simple from the outside: follow the market while it moves in your favor, keep moving the stop behind it, and exit when the market reverses far enough. In practice, the annoying parts are all operational:

where to store API keys,
how to test connectivity before risking a live order,
how to run the trailing engine from a terminal,
how to reuse predefined profiles,
and how to integrate the same logic into Python code when the CLI is not enough.

That is what UNICORN Binance Trailing Stop Loss (UBTSL) is for.

CLI workflow

The CLI is the fastest way to use UBTSL directly from a terminal.

# add Binance API key and secret
ubtsl --createconfigini
ubtsl --openconfigini

# test connectivity
ubtsl --test binance-connectivity

# start trailing
ubtsl -m BTCUSDC -n trail --stoplosslimit 1% -e binance.com

# use a profile
ubtsl --createprofilesini
ubtsl --openprofilesini
ubtsl --profile BTCUSDC_SELL --stoplosslimit 1.5%

# cancel all open orders on the configured account/exchange
ubtsl --profile BTCUSDC_SELL --cancelopenorders

# help
ubtsl -h

The normal flow is:

create the config file,
add your Binance API key and secret,
test connectivity,
start a trailing stop directly or through a named profile.

Profiles are useful once you repeatedly trade the same market or strategy pattern. Instead of passing every detail on the command line each time, you define the profile once and then override only the values you want to change, such as --stoplosslimit.

The example above starts a trailing stop on BTCUSDC with a 1% stop-loss limit on binance.com. The profile example starts the predefined BTCUSDC_SELL setup and overrides the stop-loss limit to 1.5%.

--cancelopenorders is a practical cleanup command when you intentionally want to cancel all currently open orders on the configured account/exchange before starting fresh. Use it deliberately — it does exactly what the name says.

Python integration

UBTSL can also be used from Python when the trailing stop should be part of a larger bot or service. The exact parameters depend on the trade direction, market, profile, and execution mode you want to use, so the official example should be treated as the reference implementation:

example_binance_trailing_stop_loss.py

The important architectural point is this: UBTSL is not just a small formula that calculates a moving stop price. It is an engine around Binance execution state. It tracks the market, updates the stop logic, reacts to partial fills and finished orders, and gives you callbacks for operational handling.

A minimal SDK integration usually follows this shape:

import asyncio
from unicorn_binance_trailing_stop_loss.manager import BinanceTrailingStopLossManager


def callback_error(error_msg=None):
    print(f"ERROR: {error_msg}")


def callback_finished(msg=None):
    print(f"FINISHED: {msg}")


def callback_partially_filled(msg=None):
    print(f"PARTIALLY FILLED: {msg}")


async def main():
    with BinanceTrailingStopLossManager(
        api_key="YOUR_API_KEY",
        api_secret="YOUR_API_SECRET",
        market="BTCUSDC",
        stop_loss_limit="1.5%",
        callback_error=callback_error,
        callback_finished=callback_finished,
        callback_partially_filled=callback_partially_filled,
    ) as ubtsl:
        while not ubtsl.is_manager_stopping():
            await asyncio.sleep(1)


try:
    asyncio.run(main())
except KeyboardInterrupt:
    print("Gracefully stopping ...")

For a production bot, I would not paste this blindly and call it done. I would start from the official example, wire the callbacks into your own logging/alerting, and make sure the account, market, order side, and stop-loss behavior match your intended execution model.

Stop Parsing Raw Binance JSON by Hand (UnicornFy)

Binance's raw WebSocket frames are compact and cryptic. Here's a kline update straight off the wire:

{"stream":"btcusdc@kline_1m","data":{"e":"kline","E":1778563770000,"s":"BTCUSDC","k":{"t":1778563740000,"T":1778563799999,"s":"BTCUSDC","i":"1m","o":"81251.35","c":"81292.61","h":"81293.00","l":"81250.61","v":"1.42442","n":50,"x":false,"q":"115789.12","V":"0.81","Q":"65872.55","B":"0"}}}

Single-letter keys. Nested envelopes. Easy to mis-parse, hard to read at a glance. UnicornFy turns that into:

from unicorn_fy.unicorn_fy import UnicornFy
parsed = UnicornFy().binance_com_websocket(raw)

{
  "stream_type": "btcusdc@kline_1m",
  "event_type": "kline",
  "event_time": 1778563770000,
  "symbol": "BTCUSDC",
  "kline": {
    "kline_start_time": 1778563740000,
    "kline_close_time": 1778563799999,
    "symbol": "BTCUSDC",
    "interval": "1m",
    "open_price": "81251.35",
    "close_price": "81292.61",
    "high_price": "81293.00",
    "low_price": "81250.61",
    "base_volume": "1.42442",
    "number_of_trades": 50,
    "is_closed": false,
    "quote": "115789.12",
    "taker_by_base_asset_volume": "0.81",
    "taker_by_quote_asset_volume": "65872.55"
  }
}

You usually don't call UnicornFy directly — pass output_default="UnicornFy" to UBWA and every frame that lands in your buffer is already normalized.

Scaling Beyond a Single Process: UBDCC

A single UBLDC process can handle many markets. The moment you need redundancy or multiple consumers, the order book should stop living inside one bot process.

UBDCC turns UBLDC into a shared service. You run the cluster once, create DepthCaches there, and every bot, dashboard, or service reads the same synchronized order-book source over HTTP. Locally, the REST API listens on port 42081; in Kubernetes, it is exposed through the ubdcc-restapi service, usually on port 80 behind a LoadBalancer.

Quick local start:

pip install ubdcc
ubdcc start

Create redundant DepthCaches:

curl -X POST 'http://127.0.0.1:42081/create_depthcaches' \
  -H 'Content-Type: application/json' \
  -d '{"exchange": "binance.com", "markets": ["BTCUSDC", "ETHUSDT", "BNBUSDC"], "desired_quantity": 2}'

Query the order book via REST:

curl 'http://127.0.0.1:42081/get_asks?exchange=binance.com&market=BTCUSDC&limit_count=5'
curl 'http://127.0.0.1:42081/get_bids?exchange=binance.com&market=BTCUSDC&limit_count=5'

The important point is the URL shape:

/get_asks?exchange=binance.com&market=BTCUSDC&limit_count=5
/get_bids?exchange=binance.com&market=BTCUSDC&threshold_volume=100000

UBDCC exposes synchronized order-book data through explicit REST endpoints such as /get_asks and /get_bids. For normal consumers, the response stays focused on the requested book side. When you need operational details, debug=true adds routing and timing metadata.

curl 'http://127.0.0.1:42081/get_asks?exchange=binance.com&market=BTCUSDC&limit_count=2&debug=true'

UBDCC consists of three component types:

mgmt on 42080: cluster state and DepthCache distribution,
restapi on 42081 locally / 80 in Kubernetes: the endpoint your clients call,
DCN processes from 42082 upward: the workers running the actual UBLDC DepthCaches.

Your client calls restapi. It routes reads to the responsible DCN and management operations to mgmt.

Two posts dive into UBDCC in detail:

UBDCC Deep-Dive: Building a Trust Layer for Binance Order Books — architecture, why it exists, what problem it solves.
From pip install to a Redundant Binance Order Book Cluster — UBDCC + Dashboard Quickstart — a working cluster in minutes.

What "Production-Grade" Actually Means

Most articles compare libraries on what they do. The ones that decide whether your bot survives a year compare on what they handle when things go wrong. Here's the practical checklist that separates a weekend project from a service:

Concern	python-binance	binance-connector / official SDKs	CCXT	UBS
Automatic WebSocket reconnect	Partial / manager-dependent	Low-level / DIY	Available in CCXT Pro / exchange-dependent	Yes, managed
WebSocket API trading requests	Recent support	Yes, official SDK direction	Exchange-dependent / Pro	Yes — integrated into UBWA manager
Request-specific WS API callbacks	Limited	SDK-style / DIY routing	Abstraction-dependent	Yes
Multiple WS API streams	Limited	DIY	Abstraction-dependent	Yes — via stream IDs / labels
WebSocket sequence-gap detection (depth)	No	N/A	No	Yes (validates `U`/`u`)
Explicit out-of-sync error surface	No	N/A	No	Yes — `DepthCacheOutOfSync`
Orphaned depth-level pruning	No	N/A	No	Yes
User-data listenKey auto-renew	Yes (less robust)	DIY	N/A	Yes, robust
Subscribe at runtime without reconnect	No	N/A	No	Yes
Native asyncio `await` queue	No decoupled backpressure-aware queue	N/A	Mixed	Yes
Multi-account routing	Separate clients / application routing	Separate clients / application routing	Separate clients / abstraction-dependent	Integrated routing via stream IDs / labels
Native/Cython components with multi-arch wheels	N/A / mostly pure Python	N/A / mostly pure Python	N/A / pure Python	Yes — x86_64, aarch64, arm64
Connection-state observability	Limited / application-level	Low-level / application-level	Exchange-dependent	Built-in: stream lifecycle signals, per-stream labels, reconnect visibility, and stream-scoped log context
Cluster-scale option	No	No	No	UBDCC

This is not only for large desks. Beginners benefit from stable defaults too. A small bot is not better because its WebSocket handling is fragile, and python-binance is not automatically simpler just because it ranks first. The practical reason to look at UBS is that it makes many failure modes explicit before they become your problem.

Trust and installation notes

UNICORN Binance Suite is MIT-licensed open source. Install from PyPI or the official GitHub repositories under oliver-zehentleitner.

There have been fraudulent repositories impersonating UBWA with malware payloads, so avoid random forks, ZIP downloads, or similarly named projects. The official package names are listed above.

Where to Go from Here

Build something:

Stream market data → Kafka, ready for downstream processing: Passing Binance Market Data to Apache Kafka in Python with aiokafka
Atomic OCO take-profit + stop-loss: Buy an Asset and Instantly Create a Take-Profit + Stop-Loss OCO Sell Order
Run a redundant order-book cluster: UBDCC + Dashboard Quickstart

Understand the internals:

Why a "correct" depth cache rots if you follow the spec: Your Binance DepthCache Is Rotting
What UBDCC actually does, architecturally: UBDCC Deep-Dive
The Binance API security model and where it leaks: Binance Fixed the IP Whitelist Gap. The Disclosure Process Is Still Broken

Docs and source:

UBWA: docs · GitHub
UBRA: docs · GitHub
UBLDC: docs · GitHub
UBTSL: docs · GitHub
UnicornFy: docs · GitHub
UBDCC: docs · GitHub
Suite meta-package: docs · GitHub

Talk to humans:

Telegram: t.me/unicorndevs — the answer to most questions is one message away.
GitHub Discussions on any of the repos above.

Closing

python-binance, the official Binance SDKs, and CCXT are useful tools. They exist for real reasons. But UBS is built around a different premise: a Binance bot should not only be able to call endpoints — it should understand stream lifecycle, reconnects, order-book trust, out-of-sync states, WebSocket API routing, and failure surfaces from the beginning.

That is useful for production systems, but it is also useful for beginners. Starting small does not mean starting fragile. A stable library is not overkill just because your first script has 50 lines.

If you are building anything Binance-specific in Python, try the suite once. The install is one line. The list of things you no longer have to reinvent is the rest of this article.

Either way: name the failure modes before you ship. The libraries that make those states visible are the ones you want under your code.

This guide will be expanded into a series of deep-dives — WebSocket API request routing, WebSocket reconnect internals, stream_signals, the high_performance flag, OCO order patterns, UBDCC cluster architecture, and more. Subscribe to the UNICORN Binance Suite series to catch each one as it lands.

I hope you found this informative and useful.

Follow me on Binance Square, GitHub, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯

Keep the Why: Code Becomes Legacy When Nobody Remembers Why

Oliver Zehentleitner — Sat, 11 Jul 2026 06:47:39 +0000

Keep a Changelog records what changed. Keep the Why preserves why it changed.

I turned four months of working with AI coding agents into an open-source skill for preserving the reasoning behind a codebase.

I've been maintaining the UNICORN Binance Suite since 2019. It is a set of open-source Python packages for building automated trading systems on Binance, and parts of it have been running in production for years.

For the last few months, I have also been working with an AI coding agent on these projects every day.

Early on, I invested quite a bit of time into the harness around it:

conventions
project structure
persistent context
documentation the agent could actually use
rules for how it should work inside a mature codebase

That effort paid off.

Today I can point the agent at a piece of code and ask why something looks the way it does. In many cases, it can answer correctly without guessing.

Not because the model somehow remembers seven years of development history. It does not.

It can answer because the reasoning is still present in the repository.

That distinction matters.

The more I worked with this setup, the more obvious something became:

If structured context makes an AI agent useful in a codebase it did not grow up with, the same context should also help a human developer entering that project later.

A new developer should not have to reverse-engineer every strange retry loop, compatibility workaround or architectural boundary from the code alone. They should be able to ask:

Why is this retry logic so defensive?
Why are we not using the obvious library?
Why does this component wait for a snapshot before processing buffered events?
What broke the last time somebody simplified this?

And ideally, the answer should already live with the project.

That is the idea behind Keep the Why.

The problem

Tests preserve expected behaviour.

Git preserves changes.

Issue trackers preserve discussions, sometimes.

What often disappears is the reasoning behind the final implementation.

That creates a few very familiar problems.

Re-debate

A team discusses the same architecture question again because nobody remembers that it was already settled eighteen months ago.

The previous decision may still be correct. The reasons are simply gone.

Silent regression

Somebody finds a workaround that looks unnecessary and cleans it up.

Unfortunately, it was not unnecessary. It was the fix for a bug nobody documented properly.

The code looked ugly because reality was ugly.

Onboarding stall

A new developer sees code they do not understand and avoids touching it.

That is usually a reasonable decision. Changing unfamiliar code without context is how repeat incidents are born.

AI coding agents have the same problem, only faster. A fresh session starts with little or no project history. Without preserved rationale, the agent either spends time reconstructing it or confidently proposes the exact approach that already failed once.

This is not a new problem

Architecture Decision Records have existed for years, and they are useful.

But they require somebody to notice that a decision deserves an ADR, stop the current work and document it deliberately. Large architectural choices may get that treatment. Smaller constraints often do not.

Those smaller decisions are frequently the ones that become dangerous later:

a defensive timeout
an odd startup sequence
a compatibility branch
a strange cache invalidation rule
a library that was evaluated and rejected
a workaround linked to a production incident

They are too small for ceremony and too important to forget.

The important change is not that reasoning suddenly became valuable.

The change is that an AI agent already participates in many of the conversations where that reasoning appears. Capturing it no longer has to be a completely separate documentation task.

What Keep the Why is

Keep the Why is an open-source agent skill.

It is a SKILL.md file with supporting references and examples, based on the open Agent Skills format. There is no service, database, account or MCP server behind it.

It teaches a coding agent four related workflows.

1. Continuous capture

During normal development, the agent notices when a conversation contains useful rationale:

an architectural choice
a rejected alternative
a production constraint
an incident finding
an intentional workaround
a behaviour that looks strange but is deliberate

It then updates the relevant project context at a natural checkpoint.

The goal is not to document every line of code. That would just create a second codebase, only written in Markdown.

The goal is to preserve the parts that are not obvious from the implementation itself.

2. Retrospective recovery

The skill can also be applied to an existing repository.

The agent inspects:

code
git history
issues
pull requests
existing documentation

It reconstructs what the available evidence supports and clearly marks what remains uncertain.

It should not invent a clean historical narrative just because that would look nice in a document.

Sometimes the honest result is:

We know what this does. We do not yet know why it was designed this way.

That is useful information too.

3. Knowledge-transfer interviews

This is the part I find especially interesting.

Before a long-term maintainer changes teams, leaves or retires, the agent can first analyse the repository and identify areas where the reasoning is missing.

It can then prepare focused questions:

Why does this synchronization process wait for the snapshot before applying buffered updates?

instead of:

Please explain the synchronization system.

The first question has a chance of recovering useful knowledge. The second usually produces a meeting nobody wants to attend.

For broad, mostly tacit knowledge, the process can also work the other way around: let the maintainer explain the history in their own words, then extract decisions, constraints and open questions from the conversation.

The important part is that the result becomes project knowledge, not another recording nobody will ever watch again.

4. Maintenance

Documentation can become legacy too.

So the skill also defines how to:

update existing topic files
resolve contradictions
mark old decisions as superseded
split files before they become too large
keep indexes lean enough for humans and agents
avoid creating five documents for one small decision

This is living documentation, not an archive of frozen decisions.

The structure

Keep the Why deliberately separates two kinds of project knowledge.

docs/
context/

`docs/`

This answers:

How do I use, operate, test, deploy or troubleshoot this project?

Examples:

installation
configuration
API usage
testing
deployment
operations
troubleshooting

`context/`

This answers:

Why is the project built this way?

Examples:

architectural rationale
rejected alternatives
historical constraints
incident learnings
compatibility decisions
deliberate workarounds
superseded approaches

Both layers are plain Markdown and versioned with the repository.

There is no separate AI-only knowledge store waiting to drift away from the human documentation.

The context is organised by topic, for example:

context/
├── index.md
├── architecture.md
├── synchronization.md
├── compatibility.md
└── incidents.md

I prefer this over a file-by-file shadow tree because decisions often span several files and survive refactors.

I also prefer it over one file per decision for smaller, evolving topics. Formal ADRs still make sense where they fit. Keep the Why is not trying to ban them.

What it looks like in practice

Imagine a normal implementation discussion:

You: The simpler retry mechanism caused duplicate orders during
     reconnects. Keep the stateful version even though it looks
     more complicated.

That is not just an implementation detail.

It contains:

the rejected alternative
the reason it was rejected
the failure mode
the constraint future maintainers must preserve

The agent should recognise that and update the relevant topic in context/.

Six months later, somebody finds the code and thinks:

This looks over-engineered. I can simplify it.

Chesterton's Fence, except this time the fence has a sign on it.

The rule that matters most

The core rule of Keep the Why is simple:

Never invent rationale.

Plausible-sounding historical explanations are worse than missing documentation. A blank page creates caution. A confident false explanation creates bad decisions.

Each relevant rationale entry should make clear whether its evidence is:

confirmed — supported by a maintainer or authoritative project evidence
inferred — reasonably derived, but not confirmed
unknown — the available evidence is insufficient

Separately, an entry can be marked as superseded when it was once valid but has since been replaced.

This distinction matters: evidence confidence and temporal status are two different things.

This is not decoration.

It is the difference between useful project knowledge and hallucination wearing documentation's clothes.

The second important rule is proportionality.

A self-explanatory decision may need one sentence.

A surprising architecture boundary may need:

context
decision
alternatives
consequences
evidence
conditions under which it should be revisited

Not every decision deserves a ceremony. Not every strange-looking line deserves to be forgotten either.

How it relates to existing approaches

Keep the Why is not a replacement for:

tests
README files
CONTRIBUTING.md
ADRs
issue trackers
Keep a Changelog

The name is deliberately related to Keep a Changelog.

Keep a Changelog records what changed.

Keep the Why preserves why it changed.

There is also prior work in this space:

Architecture Decision Records
git-why
Addy Osmani's documentation-and-adrs skill
Agent Decision Records (AgDR)
repository-memory and agent-context tools

I did not invent the idea that software decisions should be documented.

What I wanted was a practical combination of:

continuous capture
retrospective recovery
code-guided knowledge-transfer interviews
topic-based living documentation
repository-native storage
no required external platform

That combination grew out of how I was already working.

Where the project stands

The underlying practice is not completely new to me.

I have been testing variations of this approach in my own AI-assisted development workflow for roughly four months.

But the public project is not a copy of that private setup.

It is a new incarnation of it:

cleaned up
generalised
made cross-agent
turned into an explicit method
separated from my own repository conventions
packaged as an open-source skill

That means it now has to prove itself in real use — and mature through it.

The initial structure looks reasonable to me. The real test is what happens across different repositories, teams and agents.

I expect some parts to change.

For example:

When does the agent capture too much?
When does it ask too little?
Which structure works for a small library and which one works for a large multi-repository system?
How much classification is useful before it becomes bureaucracy?
When should a topic be split?
How do we keep old rationale from becoming trusted but stale?

There is also a small but relevant body of supporting research. A 2026 position paper audited 62 architectural decisions across two internal projects and found that roughly 23% had stale supporting evidence within two months. The sample is small and the result is not a universal law, but it supports something maintainers already know: documentation does not stay correct by existing. It has to be maintained.

I do not yet have automated cross-agent eval results or a published before-and-after study.

The eval cases exist. The public evidence does not, yet.

That is the honest state of the project.

Try it

Install it with:

npx skills add oliver-zehentleitner/keep-the-why

Or inspect and install it through GitHub:

gh skill preview oliver-zehentleitner/keep-the-why keep-the-why
gh skill install oliver-zehentleitner/keep-the-why keep-the-why

It is instructions only:

no scripts
no network calls of its own
no external service
no account
no database

Documentation and manual installation:

keepthewhy.com

Source, license and the actual skill:

github.com/oliver-zehentleitner/keep-the-why

Feedback is welcome

Keep the Why is young.

The base is there, but the method now needs real use outside my own projects.

I am especially interested in feedback from people working with:

mature codebases
long-running production systems
AI coding agents
developer onboarding
knowledge transfer
maintainers who have inherited code nobody wants to touch

Bug reports are useful.

Conceptual criticism is even more useful.

If the structure is wrong for your project, I want to know why. If an important workflow is missing, propose it. If another project already solves part of this better, point me to it.

The project is open source because I do not think this should become another private knowledge silo.

The whole point is to keep the reasoning with the code.

Because “ask Bob” is not documentation.

Your Binance L2 Order Book Can Be Gap-Free and Still Be Wrong

Oliver Zehentleitner — Thu, 11 Jun 2026 11:51:41 +0000

A Binance order book looks simple until you try to keep one correct for hours, days, or weeks.

At first, the task appears straightforward:

subscribe to Binance depth updates over WebSocket,
fetch an order book snapshot over REST,
apply every update in sequence,
expose the resulting bids and asks to your strategy.

That is enough to produce something that looks like a live Binance L2 order book.

It is not enough to prove that the book is correct.

A local order book can have:

no detected sequence gap,
a healthy WebSocket connection,
plausible best bids and asks,
valid-looking quantities,
and thousands of price levels that no longer exist on Binance.

This article covers the full lifecycle of a trustworthy Binance order book: initialization, gap detection, retention, resynchronization, observability, redundancy, and the point where an in-process cache should become shared infrastructure.

A wrong order book is worse than no order book. No data stops you. Bad data lies to you.

What is a Binance L2 order book?

A Level 2, or L2, order book represents aggregated liquidity at individual price levels.

For each side of the market, it contains pairs such as:

price, quantity

For example:

{
  "bids": [
    ["104250.10", "0.842"],
    ["104250.00", "1.307"]
  ],
  "asks": [
    ["104250.20", "0.514"],
    ["104250.30", "2.191"]
  ]
}

The highest bid and lowest ask form the top of book.

The full price ladder is useful for:

spread and slippage calculations,
market-depth analysis,
liquidity monitoring,
order-flow research,
market making,
arbitrage,
execution planning,
and trading-system risk controls.

Binance does not continuously send a complete order book to every client. It gives you separate pieces that your application must combine.

What Binance actually gives you

To construct a local Binance order book, you normally use:

a REST depth snapshot,
a WebSocket diff-depth stream.

The REST response gives you a bounded view of the order book at a specific lastUpdateId.

The WebSocket stream then sends incremental changes containing fields such as:

U  first update ID in the event
u  final update ID in the event
pu previous event's final update ID on relevant futures streams
b  bid updates
a  ask updates

Your code is responsible for turning those two independent data sources into one coherent state.

That requires more than applying JSON messages to a dictionary.

The first trap: the snapshot race condition

A common implementation does this:

fetch snapshot
connect WebSocket
apply updates

That ordering is unsafe.

Updates can occur after the snapshot was created but before the WebSocket subscription becomes active. Those updates are lost, and the local Binance order book starts with a silent gap.

The safer sequence is:

connect WebSocket
buffer depth events
fetch REST snapshot
discard obsolete buffered events
find the first event that continues from the snapshot
replay the remaining buffer
continue with live updates

Conceptually:

buffer = []

start_depth_stream(on_event=buffer.append)
snapshot = fetch_depth_snapshot()

last_update_id = snapshot["lastUpdateId"]

buffer = [
    event
    for event in buffer
    if event["u"] >= last_update_id
]

first_event = find_first_event(
    buffer,
    lambda event: event["U"] <= last_update_id + 1 <= event["u"],
)

apply_snapshot(snapshot)

for event in buffer[first_event:]:
    apply_depth_event(event)

The exact protocol differs slightly between Binance Spot and Futures, so do not blindly reuse a Spot implementation for Futures.

Sequence continuity is a trust boundary

Once the Binance order book is synchronized, every event must continue the sequence you already processed.

For Spot, the steady-state check is commonly based on the next expected update ID:

if event["U"] != last_update_id + 1:
    request_full_resync()
    return

For relevant Futures streams, Binance provides pu, which references the previous event:

if event["pu"] != last_update_id:
    request_full_resync()
    return

After validation:

apply_updates(event)
last_update_id = event["u"]

A broken sequence is not merely a warning.

It means your local order book no longer has a proven relationship to the exchange state.

Do not log the problem and keep serving the same book. Mark it as out of sync, stop trusting it, and initialize it again from a fresh snapshot.

Applying bid and ask updates

Each depth event contains price-level changes.

The basic rule is:

def apply_level(book: dict[str, str], price: str, quantity: str) -> None:
    if quantity == "0":
        book.pop(price, None)
    else:
        book[price] = quantity

This part is easy.

The dangerous assumption is that correct update application plus correct sequence validation guarantees a correct long-running Binance order book.

It does not.

The second trap: a gap-free order book can still rot

While maintaining the UNICORN Binance Local Depth Cache, I investigated a report that bids and asks kept growing beyond their expected size.

The implementation:

started from a valid snapshot,
processed updates in order,
removed levels when Binance sent quantity 0,
and detected broken update continuity.

It still accumulated stale price levels.

Why?

A bounded REST snapshot defines the initial view your cache can validate. The diff stream can later introduce price levels outside the active region that your application intends to maintain.

A naive implementation inserts every streamed level and removes it only when a future update explicitly sets its quantity to zero.

But a reliable cleanup event does not necessarily arrive for every price level your cache has collected. Levels can move outside the bounded region you are validating and remain in local memory indefinitely.

The result is a growing archive of plausible-looking historical price levels.

I call them:

orphaned levels,
ghost levels,
or ghost orders.

They are especially dangerous because they do not look corrupted.

A stale level such as:

104000.00 BTCUSDT bid quantity 0.73

looks completely reasonable.

Your best bid and best ask may still be correct while deeper liquidity, cumulative volume, order-book shape, and slippage estimates are increasingly wrong.

What a 25-hour Binance order book test showed

To isolate this behavior, I ran two BTCUSDT depth caches side by side for 25.10 hours.

Both received the same WebSocket data and were audited against REST snapshots at the same times.

The only relevant difference was retention:

naive cache: apply updates and delete only on quantity == 0,
fixed cache: apply the same updates but actively prune the maintained book back to its intended top-1000 corridor.

BTC moved only 1.88% during the test window. This was a calm market, not a flash crash or extreme volatility event.

At the final audit:

Implementation	Local bids	Local asks	Bid levels matching REST	Ask levels matching REST
Naive	20,758	9,116	24.09%	39.82%
Pruned	1,011	1,078	87.83%	91.74%

The naive Binance order book started almost perfectly aligned.

Then it rotted.

Open interactive 3D chart: report_naive.html

Warning: large Plotly file, about 78 MB.

Open interactive 3D chart: report_fixed.html

Warning: large Plotly file, about 41 MB.

The important lesson is:

Gap-free does not mean correct forever.

Sequence checks answer:

Did I miss a depth event?

A retention policy answers a different question:

Which price levels am I still able and willing to claim as part of my maintained L2 order book?

A production implementation needs both.

Add an explicit retention policy

If your application claims to maintain a bounded top-N Binance order book, enforce that boundary.

A simplified pruning function could look like this:


def prune_side(
    side: dict[str, str],
    *,
    descending: bool,
    limit: int,
) -> None:
    ordered = sorted(
        side.items(),
        key=lambda item: float(item[0]),
        reverse=descending,
    )

    for price, _quantity in ordered[limit:]:
        del side[price]

Applied to both sides:

prune_side(bids, descending=True, limit=1000)
prune_side(asks, descending=False, limit=1000)

For bids, higher prices are better.

For asks, lower prices are better.

The exact retention strategy depends on your use case, market, performance requirements, and the depth corridor you promise to consumers. The critical part is that the policy must exist.

An initial snapshot size alone is not a retention policy.

Resync must be normal behavior

Many trading systems treat resynchronization as an exceptional failure.

It should be treated as part of normal order book lifecycle management.

A resync may be required after:

a missing update ID,
an invalid first buffered event,
a WebSocket reconnect,
a buffer overflow,
an internal processing delay,
an invariant violation,
a crossed local book,
or an operator-requested refresh.

A robust state machine should expose states such as:

INITIALIZING
SYNCHRONIZED
OUT_OF_SYNC
RESYNCING
STOPPED

Consumers should never have to infer those states from stale timestamps or log files.

Before returning bids or asks, the service should know whether the Binance order book is currently trustworthy.

Do not silently serve stale order book data

Imagine an API consumer requests BTCUSDT asks while the cache is resynchronizing.

The convenient behavior is to return the last known data with HTTP 200.

The honest behavior is to return an explicit trust-state error.

For example:

{
  "error_id": "#6000",
  "message": "DepthCache 'BTCUSDT' for 'binance.com' is out of sync!"
}

The consumer can then choose to:

retry,
temporarily reduce confidence,
use a redundant replica,
disable a strategy,
or stop trading that market.

That decision belongs to the consumer.

The order book layer's responsibility is to preserve the truth about its own state.

Validate more than update IDs

Sequence validation is essential, but useful runtime invariants go further.

Examples include:

Invariant	Possible meaning
`best_bid >= best_ask`	crossed or corrupted local order book
unexpected update-ID transition	missing, duplicated, or reordered event
event buffer exceeds capacity	consumer cannot keep up
stream silence exceeds threshold	dead or stalled connection
maintained depth grows beyond policy	missing or ineffective pruning
cache age exceeds threshold	stale data path
replica states disagree for too long	one cache may be unhealthy

A crossed book should be handled carefully because fast-moving markets and independently timed observations can complicate comparisons. But inside one consistently applied local state, impossible relationships are valuable warning signals.

The broader rule is simple:

Make corruption observable before it reaches the strategy.

Why one correct local order book is still not enough

For one bot and one market, an in-process Binance L2 order book can be a reasonable design.

Then the system grows.

You add:

another strategy,
a dashboard,
a monitoring service,
an alerting process,
a backtesting or research consumer,
a Node.js application,
a Go execution service,
or a script that only needs the top five asks.

If each application reconstructs the same Binance order book independently, each one now owns:

WebSocket lifecycle handling,
REST snapshot initialization,
buffering,
sequence validation,
pruning,
resync,
memory management,
and exchange rate-limit consumption.

A reconnect storm duplicates the same initialization work.

Two processes can temporarily hold different views of the same market.

Restarting application logic also destroys and rebuilds market-data state that did not need to be coupled to that application.

At this point, the order book is no longer an implementation detail of the bot.

It is infrastructure.

Treat the Binance order book as a shared service

The architectural shift is:

one synchronized order book layer
many independent consumers

Instead of:

bot A -> Binance -> local BTCUSDT cache
bot B -> Binance -> local BTCUSDT cache
dashboard -> Binance -> local BTCUSDT cache

use:

Binance
   |
shared synchronized depth-cache layer
   |          |          |
 bot A      bot B     dashboard

This provides a single place to implement:

snapshot and WebSocket synchronization,
sequence validation,
retention,
resync,
cache-state reporting,
replicas,
failover,
monitoring,
and client access.

The consuming application can remain focused on strategy or analysis.

A practical implementation with UBDCC

I built the open-source UNICORN Binance DepthCache Cluster, or UBDCC, for this architecture.

UBDCC runs synchronized Binance DepthCaches as a standalone service and exposes them over HTTP/JSON.

It is written in Python, but clients do not need to be Python applications.

Anything that can call an HTTP endpoint can consume the same Binance order book:

Python,
JavaScript,
Go,
Rust,
Java,
C#,
PHP,
Bash,
dashboards,
spreadsheets,
or internal services.

A local test setup starts with:

python3 -m pip install ubdcc
ubdcc start --dcn 4
ubdcc-dashboard start

Create a BTCUSDT DepthCache with two replicas:

curl -X POST 'http://127.0.0.1:42081/create_depthcaches' \
  -H 'Content-Type: application/json' \
  -d '{
    "exchange": "binance.com",
    "markets": ["BTCUSDT"],
    "desired_quantity": 2
  }'

Query the first five asks:

curl 'http://127.0.0.1:42081/get_asks?exchange=binance.com&market=BTCUSDT&limit_count=5'

Query the first five bids:

curl 'http://127.0.0.1:42081/get_bids?exchange=binance.com&market=BTCUSDT&limit_count=5'

With two replicas, the same market exists on separate DepthCache nodes. If one node fails, another synchronized replica can serve the request.

UBDCC is not:

a trading strategy,
an execution engine,
a backtesting framework,
or a promise of profitable trading.

It is a market-data layer.

Local library, service, or cluster?

Not every project needs distributed infrastructure.

Use a local in-process Binance order book when:

you have one process,
only one consumer needs the data,
temporary loss during restart is acceptable,
and you are prepared to own synchronization and retention logic.

Use a standalone shared service when:

several applications need the same markets,
applications use different programming languages,
rebuilding caches during every deployment is wasteful,
or you want one observable trust state.

Use replicas or a cluster when:

order book availability matters,
one process must not be a single point of failure,
you maintain many markets,
initialization pressure must be distributed,
or consumers require explicit failover.

The architecture should follow the reliability contract you actually need.

A checklist for a trustworthy Binance L2 order book

Before trusting a local or remote Binance order book, verify that the implementation can answer all of these:

Initialization

Does it subscribe before fetching the snapshot?
Does it buffer WebSocket events while the snapshot is in flight?
Does it discard stale events correctly?
Does it find the correct first applicable update?

Continuity

Does it validate Spot and Futures sequences using the correct fields?
Does any continuity failure trigger a full resync?
Can the event buffer overflow silently?

State management

Is synchronization state explicit and queryable?
Are reads rejected or marked while the cache is out of sync?
Are reconnect and resync events observable?

Long-running correctness

Is there an explicit retention boundary?
Are old levels pruned?
Does maintained depth remain bounded?
Is the complete book audited periodically, not only best bid and ask?

Operations

Can the cache recover without restarting the strategy?
Are metrics and health states exposed?
Can replicas fail independently?
Can consumers distinguish fresh data from stale data?

If any answer is “I do not know,” that is where to investigate next.

Final thoughts

Most Binance order book tutorials stop after they have combined one REST snapshot with one WebSocket stream.

That is the beginning, not the end.

A production-grade Binance L2 order book needs at least four separate guarantees:

Correct bootstrap

The snapshot and buffered events form one continuous initial state.
Continuous sequence validation

Missing or reordered updates cause a loud resync.
Explicit retention

The cache does not silently become a museum of historical price levels.
Observable trust state

Consumers know whether the book is synchronized before using it.

And once several applications need the same data, there is a fifth:

Shared, redundant infrastructure Order book reconstruction should not be duplicated inside every bot.

The difficult part is not receiving Binance depth data.

The difficult part is knowing when that data still deserves to be called an order book.

Source code and related research

Questions, corrections, failed test cases, and contradictory results are welcome in the comments.

I hope you found this informative and useful.

Follow me on Binance Square, GitHub, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\_(ツ)_/¯