DEV Community: Sunil Prakash

Every AI toolchain is inventing its own safety layer.

Sunil Prakash — Tue, 12 May 2026 18:26:09 +0000

Same policy. Three runtimes.

# Claude Code, with @jamjet/claude-code-hook installed as a PreToolUse hook:
> Delete the old customer records from the staging DB.

  Tool request: bash.shell_exec
  Args: psql -c "DELETE FROM customers WHERE created_at < '2024-01-01'"

  JamJet policy: BLOCKED (rule: shell.exec)
  Audit: ~/.jamjet/audit/2026-05-11/claude-code-hook.jsonl

# OpenAI Agents SDK (TS), with @jamjet/openai-guardrail wired into a refund tool:
JamjetPolicyBlocked: JamJet policy: BLOCKED
  (tool: payments.refund, rule: payments.*)

  Audit: ~/.jamjet/audit/2026-05-11/openai-guardrail.jsonl

# Claude Desktop talking to a Postgres MCP server, fronted by @jamjet/mcp-shim:
{"jsonrpc":"2.0","id":7,"error":{
  "code": -32000,
  "message": "JamJet policy: BLOCKED (rule: *delete*)",
  "data": {"tool": "postgres.delete_all_rows", "audit": "mcp-shim.jsonl"}
}}

Same policy.yaml. Three runtimes. One audit log.

The models are real. The tool calls came from real agent loops. The destructive payloads never reached the tool function.

The fragmentation problem

The market is converging on "control AI agent actions." But the primitives are not portable.

Anthropic shipped Claude Code hooks — PreToolUse, PostToolUse, Notification, and friends. They run as subprocesses, get JSON on stdin, and decide whether the tool call proceeds. OpenAI ships tool guardrails in the Agents SDK — Python (and now TS) callables you attach to a tool, with tripwire booleans that abort the run. The MCP ecosystem is sprouting gateways and proxies for the same purpose: MCPX, IBM ContextForge, Microsoft's MCP Gateway, Lasso Security's MCP Gateway — all reasonable answers to the same wire-level question.

Each one is competently designed for its own context. None of them speak the same policy.

A real team I talked to last month runs Claude Code for engineering workflows, OpenAI Agents SDK for a customer-facing copilot, and two MCP servers wired into Cursor for ad-hoc database work. Their security review asked one question: what can the agents do?

The honest answer required reading a settings.json, a Python guardrail file, two MCP gateway configs in different YAML dialects, and an internal Confluence page describing the production if-statements. Three audit trails in three formats. Three approval flows — one Slack bot, one PagerDuty escalation, and one human paging through the OpenAI trace viewer.

The platforms are not the problem. The hook API is good. The guardrail API is good. The MCP proxy pattern is good. The problem is the seam between them — every team writes their own.

The thesis

JamJet is the action-control plane for AI agents. One policy file. One audit trail. Across hooks, guardrails, MCP gateways, SDKs, and custom runtimes.

The portable layer underneath all of them is a single policy.yaml schema and a single audit JSONL schema. Every adapter reads the same YAML, writes the same JSONL. jamjet audit show tails the lot in one chronological view.

Phase 2 shipped five packages today: @jamjet/cloud@0.3.0, @jamjet/claude-code-hook@0.1.0, @jamjet/mcp-shim@0.1.0, @jamjet/openai-guardrail@0.1.0, and @jamjet/cli@0.1.0 on npm; plus jamjet 0.8.3 on PyPI with jamjet.integrations.openai_guardrail as the Python sister. Source at jamjet-labs/jamjet-policy.

Three adapters in one paragraph each

@jamjet/claude-code-hook wires into Claude Code's PreToolUse hook. One line in ~/.config/claude-code/settings.json:

{ "hooks": { "PreToolUse": [
    { "command": "jamjet-hook --policy ~/.jamjet/policy.yaml" }
] } }

Every tool call — native or MCP — runs through the policy before Claude Code invokes it. What it does: enforce, audit, and surface approval prompts as blocks in v0.1. What it does not do: replace Claude Code's own hook system. It is the hook.

@jamjet/mcp-shim sits between an MCP client (Claude Desktop, Cursor, an OpenAI Agents SDK MCP client) and any MCP server. You swap the server's command for the shim, pass the policy path, and put the real server after --:

{ "mcpServers": { "postgres": {
  "command": "npx",
  "args": [
    "-y", "@jamjet/mcp-shim", "--policy", "~/.jamjet/policy.yaml",
    "--server", "postgres", "--",
    "postgres-mcp", "--db", "postgresql://localhost/mydb"
  ]
} } }

The shim relays MCP traffic transparently. On a blocked tools/call, it returns a JSON-RPC error to the client — and the real MCP server never sees the request. What it does not do: replace the MCP protocol. It speaks MCP on both ends.

@jamjet/openai-guardrail (and its Python sister, jamjet.integrations.openai_guardrail) plugs into the OpenAI Agents SDK's inputGuardrails API. One line on a tool definition:

import { tool } from 'openai-agents'
import { jamjetGuardrail } from '@jamjet/openai-guardrail'

const refund = tool({
  name: 'payments.refund',
  inputGuardrails: [jamjetGuardrail({ policy: '~/.jamjet/policy.yaml' })],
  execute: refundCustomer,
})

Blocks throw JamjetPolicyBlocked. Approval-required calls throw JamjetApprovalRequired in v0.1 — the SDK aborts the run, audit gets written, and the run id is recoverable. What it does not do: replace the SDK's tripwire pattern. It is a tripwire.

The unified policy and audit

The policy file every adapter reads:

version: 1
rules:
  - { match: "*delete*",   action: block }
  - { match: "shell.exec",  action: block }
  - { match: "payments.*",  action: require_approval }
  - { match: "database.read_*", action: allow }
audit:
  destination: ~/.jamjet/audit

Glob match. Four actions: allow, block, require_approval, audit. Same shape in every adapter.

The audit log every adapter writes:

$ jamjet audit show
v 2026-05-11T10:14:02Z  claude-code-hook    fs.read_file           ALLOWED
x 2026-05-11T10:14:18Z  claude-code-hook    bash.shell_exec        BLOCKED               shell.exec
x 2026-05-11T10:21:47Z  mcp-shim            postgres.delete_rows   BLOCKED               *delete*
~ 2026-05-11T10:33:11Z  openai-guardrail    payments.refund        WAITING_FOR_APPROVAL  payments.*
v 2026-05-11T10:41:55Z  python-sdk          customers.search       ALLOWED
x 2026-05-11T10:52:09Z  openai-guardrail    db.drop_table          BLOCKED               *delete*
v 2026-05-11T11:07:33Z  mcp-shim            github.list_issues     ALLOWED

Four files in ~/.jamjet/audit/2026-05-11/, one row per decision, sorted by timestamp. Pending approvals live in ~/.jamjet/pending/<run-id>.json and clear via jamjet approve <run-id> or jamjet reject <run-id>. The audit format is documented in the conformance spec, and the v1 schema is what each adapter is tested against in CI.

This is the part of the launch we are most willing to defend. That answer to "what can the agents do?" — read it once, in one place.

What's honest

Each adapter is at v0.1. The policy YAML and audit JSONL shapes are committed to v1 and covered by conformance tests across all four adapters. Adapter-specific options will evolve in minor versions.
Approval surfaces as exceptions or blocks in v0.1 for hook, guardrail, and Python adapters. The filesystem flow works end-to-end today — jamjet approve <run-id> flips a pending file and the next run unblocks. SDK-integrated approval (the OpenAI Agents SDK approval API, Claude Code's native settings surface) and a web UI both land with JamJet Cloud sync in v0.2.
MCP shim is stdio only in v0.1. HTTP/SSE MCP transports land in Phase 3 alongside the Java/Spring adapter.
JamJet Cloud sync — shared team policies, cloud audit retention, signed approvals — is the v0.2 milestone. Today's flow is local-only by design, so nothing leaves the developer's machine unless you opt into Cloud.
One Phase 1 line still applies: the demo agent prompts are real, the enforcement path is real, the audit is real. Pre-baked deterministic agents are clearly labelled as such.

Try it

# Claude Code hook:
npm i -g @jamjet/claude-code-hook

# MCP shim (zero-install):
npx -y @jamjet/mcp-shim --help

# OpenAI Agents SDK guardrail (TS):
pnpm add @jamjet/openai-guardrail
# or Python:
pip install jamjet  # includes jamjet.integrations.openai_guardrail

# Unified CLI:
npm i -g @jamjet/cli
jamjet audit show

Star jamjet-labs/jamjet-policy — the Phase 2 monorepo.
Read the Phase 1 launch post for the deeper argument about why the runtime, not the model, is the safety boundary.
Join the JamJet Discord to talk through your toolchain — we want to know which extension points to plug into next.

Phase 3 is the Java/Spring adapter, MCP HTTP/SSE transport, and JamJet Cloud sync. Same policy. More surfaces.

Your AI agent already emits OpenTelemetry. Why aren't you watching it?

Sunil Prakash — Sat, 09 May 2026 02:16:14 +0000

TL;DR: Spring AI, LangChain4j, Koog (Kotlin), the Python OpenLLMetry-style instrumentations, and the Go OTel SDKs all emit gen_ai.* spans natively now. So you don't need a vendor SDK to make your agent observable — you need an OTLP endpoint that knows what to do with the spans your framework is already throwing on the wire. Here's what that looks like in three lines of YAML or one Kotlin extension.

Someone on your team shipped an LLM agent two months ago. Today it ran up a $400 bill in twenty minutes, hallucinated a refund policy to a real customer, and got stuck in a tool-calling loop that retried the same broken payments.create call seventeen times before the rate limiter caught it.

You'd like to know which of those things happened first, which agent was responsible (you're up to four now), what the user typed, and why the planner decided that calling the payments API was a reasonable response to "how do I unsubscribe."

If you're observing your agents the same way you observe your other services, you can answer maybe two of those questions and only after a long Slack thread with the engineer who wrote the prompt. The trace span called POST /chat doesn't help you. Neither does the metric for p99 latency on /v1/agent/run.

This post is about why that gap exists, why it's about to close, and what to do about it today.

The agent observability gap

Two existing approaches sort of work and mostly don't:

Generic APM (Datadog, New Relic, Honeycomb-as-default-config) treats your agent like any other HTTP service. You get latency histograms, error rates, and a top-level span. You don't get the prompt, the model, the token counts, the tool calls, or the cost. The signal is buried under "request body" or not captured at all.

Vendor LLM-observability SDKs (Langfuse, Helicone, Phoenix, the proprietary ones) capture all the right signals but ship as a heavy SDK that you bolt onto your service. Every framework upgrade is now a coordination problem. Every backend switch is a rewrite. And the more frameworks your stack uses (Spring AI for the orchestrator, LangChain4j for the rag service, Koog for that one Kotlin pilot), the more SDKs you carry.

Neither is the right shape. The right shape is: your framework emits standard signal, your backend understands standard signal, you change zero application code.

Until recently that wasn't possible. The OpenTelemetry community had been working on the gen_ai.* semantic conventions for a year, but framework support was uneven and the conventions kept shifting.

That changed in the last six months. Concretely:

Spring AI 1.0 emits gen_ai.client.chat, gen_ai.tool.execute, and friends via Micrometer Observations.
LangChain4j emits the same via its ChatModelListener API.
Koog 0.8 ships a first-class OpenTelemetry feature with addDatadogExporter, addLangfuseExporter, addWeaveExporter.
Python OpenLLMetry / OpenInference instrumentations (Anthropic, OpenAI, LangChain, LlamaIndex) emit the same conventions and stream through standard OTel exporters.
Go's otel-instrumentation-genai is in alpha with the same shape.

In other words: the signal is on the wire, in standard form, regardless of which framework your team picked. What's missing is a backend that does something useful with it.

The four-line Spring AI version

Stock Spring Boot 3.5 + Spring AI 1.0. No vendor SDK on the classpath. Just the standard OTel pieces (micrometer-tracing-bridge-otel, opentelemetry-exporter-otlp).

In application.yml:

management:
  otlp:
    tracing:
      endpoint: ${JAMJET_API_URL}/v1/otlp/v1/traces
      headers:
        authorization: "Bearer ${JAMJET_API_KEY}"
  tracing:
    sampling:
      probability: 1.0

That's it. Spring AI's gen_ai.client.chat spans get serialized as standard OTLP/HTTP-protobuf and posted to a JamJet Cloud project. Demo: jamjet-runtime-java/examples/spring-ai-engram-cloud-demo.

The same pattern works against any OTLP-aware backend. The endpoint URL is the only thing that varies.

The Kotlin Koog one-liner

AIAgent(...) {
    install(OpenTelemetry) {
        setServiceInfo(serviceName = "memory-agent", serviceVersion = "1.0")
        addJamjetCloudExporter()  // reads JAMJET_API_KEY from env
    }
}

About 20 lines wrapping the standard OtlpHttpSpanExporter. Demo: jamjet-runtime-java/examples/kotlin-koog-engram-cloud-demo. We've filed an upstream YouTrack issue proposing this lands in agents-features-opentelemetry-jvm directly.

And for Python / Go folks

The same shape works:

Python:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.jamjet.dev/v1/otlp/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="authorization=Bearer ${JAMJET_API_KEY}"

Plus pip install opentelemetry-instrumentation-anthropic (or -openai, -langchain, etc.) and a one-line instrument() call. The OpenInference and OpenLLMetry projects each ship instrumentations for the major frameworks.

Go:

Standard otelhttp for the LLM client wrapper, plus otlptracehttp.New(...) configured to point at /v1/otlp/v1/traces. The instrumentation surface is younger but moving fast.

The point: once your framework speaks gen_ai.* OTel, the only language-specific code you write is the exporter setup. And that's stock OTel boilerplate, not vendor-specific.

What you get on the other side

The interesting question, which generic OTel backends won't help you with, is what the receiver does with these spans. The signals an agent owner actually wants:

Multi-agent network graph — every cross-agent call is a node, edges show who-called-whom with cost and latency rolled up per edge. (W3C traceparent plus a jj tracestate segment links agents across HTTP hops.)
Cost rollups per agent / model / end-user — computed server-side from gen_ai.usage.*_tokens against current vendor pricing. No pricing table in your app.
Failure-mode pie chart — typed exception classification, not just "HTTP 5xx" buckets.
Cross-agent identity — when a user request fans out across three agents, you see the same end-user-id stitched across all of them.
Policy enforcement + audit export — Ed25519-signed JSON+CSV+PDF audit packages for the SOC2-ish surface, OTLP-formatted exports for SIEM tools (Splunk, Datadog Logs).

If "the safety layer behind your AI agents" is something you've been trying to articulate to your CTO, that's the shape we're building for.

Why this architecture is the durable bet

Three reasons stock-OTel-plus-LLM-aware-backend wins over vendor SDKs over the next two years:

No SDK on the classpath / requirements.txt / go.mod. The exporter is already in your app for HTTP tracing — you change one URL.
Backend-portable. Every line in those demos works against Honeycomb, Tempo, Jaeger, Datadog, or a self-hosted OTel collector. That's a real CTO-pitch argument when "vendor lock-in" comes up in the procurement review.
The frameworks are doing the work. Spring AI's Observation handlers, LangChain4j's listeners, Koog's OpenTelemetry feature, Python OpenLLMetry instrumentations — these aren't vendor projects. They're the framework's own contracts. Every release brings new signals for free.

Try it

Demos: github.com/jamjet-labs/jamjet-runtime-java
Cloud sign-up: jamjet.dev (free tier)
Spring Boot starter on Maven Central (for users who want a richer in-process path than stock OTLP): dev.jamjet:jamjet-cloud-spring-boot-starter:0.2.0

If you're at Devoxx this week and want to see this running against a real Spring AI or Koog agent, drop me a line — happy to do a five-minute hallway walkthrough. If your stack is Python or Go and you'd like the equivalent demo for your language, that's the next post — let me know in the comments which framework so I can pick the right starting point.

If you've got opinions on what AI-agent observability should look like, especially the bits I've glossed over (multi-tenancy, on-prem, BYO collector), the comments are open.

The State of Memory in Java AI Agents (April 2026)

Sunil Prakash — Tue, 07 Apr 2026 17:12:08 +0000

This post was originally published on jamjet.dev.

TL;DR

If you're building AI agents in Java today, your options for persistent memory range from "store the last 20 chat messages in Postgres" to "run a Python service in a sidecar container and call it over HTTP." There is no Java-native equivalent to Mem0, Zep, or Letta — the libraries Python developers reach for when they need real memory.

This post is a tour of every option a Java developer has in April 2026, why most of them stop at chat history, what "real memory" should actually mean, and one library we shipped to fill the gap.

The scenario every Java AI developer recognises

You're building an AI agent in Spring Boot. Maybe it's a customer support copilot, maybe it's a coding assistant, maybe it's a research agent. You wire up Spring AI or LangChain4j, write a few tools, and the first conversation works.

Then your user comes back the next day. The agent doesn't remember them. It doesn't remember they're allergic to peanuts. It doesn't remember they're working on the Acme migration. It doesn't remember they prefer verbose explanations. Every conversation starts from zero.

You search for "Java AI agent memory" and end up with three kinds of results:

Tutorials on how to store chat messages in Postgres
Marketing pages for Mem0 and Zep — Python only
GitHub issues asking why there's no Java SDK

This is the gap.

"Memory" means three different things

Before we tour the libraries, we need to be precise. There are at least three different things people mean when they say "agent memory":

1. Conversation history. The last N messages of the current session. Solved problem — every framework ships this.

2. State checkpointing. Snapshots of agent execution state for resume and replay. Solved by LangGraph, Koog persistence, Temporal-style runtimes.

3. Long-term knowledge memory. Facts about the user, their preferences, their projects, their history — extracted from conversations, stored durably, retrievable across sessions, and de-conflicted when they change. This is what Mem0 and Zep do. It is not solved on the JVM.

The rest of this post is about the third one.

What real memory needs

Fact extraction. An LLM reads a conversation and pulls out discrete, atomic facts.
Conflict detection. When a new fact contradicts an old one, the system invalidates the old fact.
Hybrid retrieval. Vector + keyword + graph walk fused together.
Temporal reasoning. Facts have validity windows.
Token-budgeted context assembly. Pick which facts go in the prompt and respect the budget.
Decay and consolidation. Stale facts fade, frequent facts get promoted, duplicates merge.

Tour: every option Java developers have today

LangChain4j ChatMemory

Most popular JVM AI framework. Ships ChatMemory interface with MessageWindowChatMemory and TokenWindowChatMemory. Persistence via developer-implemented ChatMemoryStore.

What it does: stores message objects, respects token/count limits. What it does not do: extract facts, deduplicate, retrieve semantically, reason about time. The docs are explicit — ChatMemory is a container abstraction.

Spring AI ChatMemory

Shipped GA in 2025 with broad backend support: JDBC, Cassandra, Mongo, Neo4j, Cosmos DB. Three advisors plug it into ChatClient.

The VectorStoreChatMemoryAdvisor is the closest thing to "semantic memory" — it indexes raw messages in your VectorStore. But it indexes raw messages, not extracted facts. No entity model, no relationship graph, no conflict detection.

Google ADK for Java

Ships 1.0.0 with two memory implementations: InMemoryMemoryService (keyword matching only) and VertexAiMemoryBankService (Vertex AI only). Memory Bank is excellent but Google Cloud-locked.

Koog (JetBrains)

Kotlin-first framework with AgentMemory storing facts by Concept, Subject, Scope. Closest competitor on the "facts about subjects" axis.

Two caveats: Java consumption is awkward, and GitHub issue JetBrains/koog#1001 documents that AgentMemory floods prompts as facts accumulate — no token budgeting.

Embabel

Rod Johnson's JVM agent framework. Uses a blackboard pattern — shared state per agent run.

Per the maintainers: "in Embabel it's not about conversational memory so much as domain objects that are stored in the blackboard during the flow." Long-term memory is an explicit non-goal.

Mem0 Java SDK (the one that doesn't exist)

The top Google result is me.pgthinker:mem0-client-java, a community wrapper at version 0.1.3, last updated nine months ago, with 9 GitHub stars. It's a thin REST client requiring a Python Mem0 server alongside your JVM app.

No official Mem0 Java client exists. Python and Node.js only.

Zep Java SDK (also doesn't exist)

Zep's official clients are Python, TypeScript, and Go. No Java SDK.

DIY (what most teams actually do)

When Java teams need real memory today, they assemble:

Postgres + pgvector (or Qdrant) for embeddings
JdbcChatMemoryRepository for messages
Custom advisor that calls an LLM to extract facts
Custom retrieval layer combining vector and keyword search
Nightly cron job for decay and dedup
Custom token-budgeting in the prompt builder

Roughly 1,500–3,000 lines of bespoke Java per team. Quietly diverges between projects. Rarely gets temporal reasoning right. Almost never gets consolidation right.

The pattern

Every Java memory option lives in one of two boxes:

Chat history persistence (LangChain4j, Spring AI core, Embabel)
State checkpointing (LangGraph4j, Koog persistence)

Nothing in between. No JVM-native library that does fact extraction + conflict resolution + temporal graph + hybrid retrieval + consolidation in one dependency.

The Python ecosystem has had Mem0 since 2024 and Zep/Graphiti since early 2025. The Java ecosystem is roughly 18 months behind.

What we built

I run JamJet. As we built our agent runtime, the memory gap kept showing up. So we built a memory layer.

Engram is a durable memory system that does the things on the list:

Fact extraction from conversation messages via LLM
Conflict detection — vector similarity threshold plus LLM resolution
Hybrid retrieval — vector + SQLite FTS5 keyword + graph walk
Temporal knowledge graph with validity windows
Token-budgeted context assembly with three output formats
5-operation consolidation engine: decay, promote, dedup, summarize, reflect
MCP server option

Runs against SQLite by default. No Postgres, no Qdrant, no Neo4j, no Python sidecar.

import dev.jamjet.engram.EngramClient;
import dev.jamjet.engram.EngramConfig;

import java.util.List;
import java.util.Map;

try (var memory = new EngramClient(EngramConfig.defaults())) {
    memory.add(
        List.of(
            Map.of("role", "user",      "content", "I'm allergic to peanuts and live in Austin"),
            Map.of("role", "assistant", "content", "Got it, I'll remember that.")
        ),
        "alice", null, null
    );

    var context = memory.context(
        "what should I cook for dinner",
        "alice", null, 1000, "system_prompt"
    );

    System.out.println(context.get("text"));
}

Maven Central:

<dependency>
    <groupId>dev.jamjet</groupId>
    <artifactId>jamjet-sdk</artifactId>
    <version>0.4.3</version>
</dependency>

Apache 2.0. Rust runtime published as jamjet-engram on crates.io.

What it doesn't do (yet)

No Spring Boot auto-configuration yet (starter on roadmap)
No JDBC backend (SQLite-first, Postgres in 0.5.x)
No managed cloud option
No published LongMemEval / DMR scores yet (benchmarks running, not going to cherry-pick)

Try it

<dependency>
    <groupId>dev.jamjet</groupId>
    <artifactId>jamjet-sdk</artifactId>
    <version>0.4.3</version>
</dependency>

Or run it as an MCP server:

cargo install jamjet-engram-server
engram serve --db memory.db

GitHub: github.com/jamjet-labs/jamjet

If you've been quietly rolling your own memory layer in Java, I'd love to hear what you ended up with. Reach out via GitHub issues or the comments below.

Introducing Agentic AI for Serious Engineers: A Free Practical Book + Code Repo

Sunil Prakash — Fri, 27 Mar 2026 04:33:12 +0000

Agentic AI is moving fast.

There are new frameworks, new demos, new orchestration patterns, and new opinions almost every week. That is exciting, but it also creates a problem for engineers trying to build real systems.

A lot of the material online is either too abstract, too framework-specific, too hype-heavy, or too focused on demo magic instead of production reality.

I wanted something different.

So I started writing Agentic AI for Serious Engineers - a free practical book and code repo for engineers who want to build agent systems that are not just impressive in a demo, but usable, testable, observable, and trustworthy in real environments.

Why I wrote it

I kept running into the same gap.

There is plenty of excitement around agents, but much less practical material on questions like:

What actually makes a system agentic?
When should you use an agent instead of a workflow?
How should tools be designed so they are safe and reliable to call?
What does good context design look like?
How do you evaluate an agent system beyond “it seemed to work”?
Where should human approval sit in the architecture?
How do you think about reliability, security, and observability from the start?

Those are the questions this book tries to answer.

Who this is for

This book is for engineers and architects building real AI systems:

backend engineers
platform engineers
staff+ engineers
software architects
technical leads
data engineers working on production AI applications

It assumes you already understand software systems.

It does not assume you already know how to design agent systems well.

What makes it different

This project is intentionally practical.

It is not a catalog of trendy frameworks.
It is not a collection of magical claims.
It is not “plug in this library and everything works.”

Instead, it focuses on the engineering questions that matter when systems move closer to production:

tool contracts
control flow
context boundaries
evaluation
approval gates
reliability
hardening
traceability
operating tradeoffs

The goal is not just to help someone build an agent.

The goal is to help them build one with better judgment.

What’s inside

The repo currently includes:

7 chapters
2 threaded end-to-end projects
per-chapter code
tests and eval-oriented structure
diagrams, principles, and roadmap
a free online version of the book

Some of the topics include:

what “agentic” actually means
tools, context, and the agent loop
workflow-first design
multi-agent systems
human-in-the-loop architecture
evaluating and hardening agents
when not to use agents

The kind of engineer I wrote this for

I wrote this for the engineer who looks at agentic AI and thinks:

This is interesting.

But how do I build it in a way I can actually trust?

That is the center of gravity of the book.

Not anti-agent.

Not pro-hype.

Just serious about engineering.

Read it free

You can read the book and explore the code here:

[https://github.com/sunilp/agentic-ai]

If you end up reading it, I’d genuinely love feedback on:

what feels most useful
what is still unclear
what you’d want covered more deeply

I’m continuing to improve it, and I’d love for it to become a genuinely useful resource for engineers building the next generation of AI systems.

Your AI CLI Writes Code. Mine Tells You What It'll Break.

Sunil Prakash — Sun, 22 Mar 2026 15:18:05 +0000

AI CLI tools are everywhere right now. Claude Code, Gemini CLI, GitHub Copilot in the terminal — they'll write your code, refactor your modules, even run your tests.

But ask any of them: "If I rename this function, what breaks?"

They'll scan the files they can see, make their best guess, and probably miss the SQL view that reads the column you're about to change. Or the Java batch job that calls your Python function through a stored procedure. Or the dbt model downstream of the table your migration is about to alter.

That's not a knock on AI. It's just not what LLMs are built for. Dependency analysis needs deterministic static analysis, not probabilistic text generation.

The gap in every AI CLI

Here's what I noticed building with these tools: they're incredible at writing code but terrible at understanding what already depends on it.

Ask Claude Code to "add retry logic to the HTTP client" — brilliant. Ask it "what will break if I change the response shape of getUser" — it'll read a few files and give you a confident answer that misses half the callers.

That's because LLMs work with whatever fits in context. Your codebase has thousands of files. The SQL stored procedure that calls your function through EXEC isn't in the context window.

Static analysis that crosses language boundaries

I built Jam to fill this gap. It's a developer CLI with 40+ commands, but the one that keeps saving me is jam trace --impact.

It uses tree-sitter to parse your entire workspace — TypeScript, Python, Java, and SQL — builds a SQLite index of every function, every call site, every import, and every SQL column reference. Then gives you a deterministic answer:

$ jam trace updateBalance --impact

Impact Analysis for updateBalance
───────────────────────────────────
Direct callers:
  PaymentService.processRefund()  [Java]
  BATCH_NIGHTLY_RECONCILE         [SQL]

Column dependents:
  VIEW v_customer_summary   (reads customer.balance)
  PROC_MONTHLY_STATEMENT    (reads customer.balance)

Risk: HIGH — 2 callers across 2 languages, 2 column dependents

No hallucination. No "I think these files might be affected." Two callers in two languages, two column dependents, risk level HIGH. Deterministic.

Why LLMs can't do this (yet)

Context window limits — Your 200-file Java project with SQL migrations doesn't fit in any context window. Static analysis indexes everything.
Cross-language boundaries — A Java class running EXEC update_user is calling a SQL stored procedure. LLMs see a string. Tree-sitter sees a cross-language call.
Column-level tracking — When a SQL view reads customer.balance, and your function writes to customer.balance, that's a dependency. No LLM tracks this.
Determinism — Ask an LLM the same question twice, get different answers. Ask jam trace twice, get the same graph. For impact analysis, you need guarantees, not guesses.

Not replacing AI — complementing it

Jam isn't anti-AI. It literally has AI built in — jam ask, jam go (agentic execution), jam commit (AI-powered commit messages), jam review. It works with Ollama, Copilot, OpenAI, Anthropic, and Groq.

But for the question "what breaks if I change this?" — AI is the wrong tool. You wouldn't ask ChatGPT to run your test suite. You shouldn't ask it to trace your dependency graph either.

The best workflow: use Claude Code or Gemini CLI to write the change, then use jam trace --impact to verify the blast radius before you ship.

# Trace any symbol's callers and callees
jam trace createProvider --depth 5

# Get the full impact report
jam trace updateBalance --impact

# Output as Mermaid diagram for docs
jam trace handleRequest --mermaid

# JSON for CI/automation
jam trace processPayment --impact --json

How it works

Tree-sitter parsing — Builds ASTs for TypeScript, Python, Java, SQL
Symbol extraction — Functions, classes, methods, imports, call sites
Cross-language detection — Java EXEC/CALL → SQL procedures. SQL column refs in SELECT/UPDATE/INSERT/DELETE
SQLite index — Local database, fast graph queries, incremental updates
Impact analysis — Walks the graph upstream, finds column dependents, calculates risk

The index rebuilds in seconds. No cloud. No API calls. Pure local static analysis.

Try it

npm install -g @sunilp-org/jam-cli
jam trace <any-function-name>
jam trace <any-function-name> --impact

No API key needed for trace — it's pure static analysis. The AI features (ask, go, commit, review) auto-detect your provider.

978 tests. MIT licensed. Works everywhere Node runs.

GitHub | Website | npm | VSCode Extension