Why I Use JSONL: The Boring Format That Makes AI Systems More Trustworthy
I use JSONL for a reason that has almost nothing to do with the fact that it is easy to generate. AI makes syntax cheap. The decision underneath it is what matters.
JSONL is boring on purpose
JSONL—JSON Lines—is one JSON object per line. There is nothing impressive about that description. That is part of the appeal.
In my own systems, I use JSONL-style streams for things like run events, tool calls, routing decisions, review events, observability, evidence, audit history, and export layers. I do not use it as a replacement for every database. I use it where the sequence of what happened matters.
A database is often trying to answer: What is true right now? An event stream is often trying to answer: What happened, in what order, and can I prove it? Those are different jobs.
One record per line is a useful constraint
Each line can represent one event: a tool was called, a route was selected, a review occurred, a result was produced, a heartbeat was recorded. That gives me a natural unit of work.
I can append a new event instead of constantly rewriting history. I can inspect the stream, process it incrementally, split it, archive it, transform it, or move it between systems without first inventing a giant custom document format.
The habit I care about is simple: record what happened instead of quietly replacing what happened with the latest version of the story.
AI systems need memory, but they also need receipts
If an agent made a decision, I want to know what it saw. If it called a tool, I want the tool call recorded. If a routing rule sent a task somewhere, I want the routing event. If the model changes tomorrow, I want enough history to compare behavior instead of relying on a vague memory that the old version seemed better.
That history becomes useful for replay, evaluation, auditing, debugging, and migration. For me, that is not a logging preference. It is a trust-design decision.
Portability matters before you need it
If prompts, outputs, tool traces, reviews, and evaluation history only exist inside one platform, the platform is holding more than your workload. It is holding your ability to understand your own system.
A plain line-delimited text format gives me an escape hatch. JSON is understood everywhere. A line is a convenient boundary. I do not need a special SDK just to understand the history.
Replay is one of the reasons I care so much
AI systems are probabilistic. Prompts, tools, policies, models, and data change. I want enough structure to ask what changed between two runs, whether a router made a different choice, whether a tool returned different data, whether a reviewer overrode the agent, and whether I can feed the same history through a new evaluator.
JSONL is not my source of truth for everything
Current mutable state usually belongs in a proper database or another authoritative store. Permissions, queues, account state, active records, locks, and relationships need real state management.
JSONL is strongest for me as an event, audit, replay, evaluation, and transfer layer. Using a simple format everywhere would not be simplicity. It would be refusing to distinguish between different kinds of data.
The professional signal is the decision
Putting JSONL on a resume is weak evidence. A more useful statement is: I chose JSONL for append-only event streams because I wanted agent actions to be auditable, replayable, portable, and separable from mutable application state.
That says something about how I think: failure recovery, observability, migrations, evaluation, and the difference between current state and historical evidence.
AI makes judgment more valuable, not less
The easier it becomes to generate code, the less impressed I am by the existence of code. I care more about the constraints around it: why this format, why this boundary, what are we preserving, what can fail, what needs to be reversible, and what evidence would tell us the design is wrong.
AI can help implement the answer and challenge the answer. I still want to own the tradeoff. That is why a small technical choice like JSONL matters to me. It is one piece of evidence that I am paying attention to how the system behaves after the demo is over.