Forem: varun pratap Bhardwaj

I Built an OS for AI Agents — Here's What I Learned

varun pratap Bhardwaj — Fri, 17 Apr 2026 10:02:46 +0000

I spent the last six months building an operating system for AI agents. Not a framework. Not a wrapper around OpenAI's API. A runtime that handles routing, quality, memory, cost management, and execution topology — the 80% of agent infrastructure that every team rebuilds from scratch.

It's called Qualixar OS, it just went public, and I want to be honest about what works, what doesn't, and what I learned along the way.

The problem nobody warned me about

I'm a solution architect with 15 years of enterprise IT experience. When I started building multi-agent systems, the agents themselves were the easy part. Getting Claude to analyze a document or GPT-4o to classify a ticket took an afternoon.

Then I spent the next three months building everything around them.

Routing logic that could pick the right model based on cost, latency, and quality constraints — not just hardcoded model names. A judge pipeline that could evaluate whether an agent's output was actually good. Memory that persisted between sessions. A way to run agents in parallel, in pipelines, in hierarchies, in debate configurations, without rewriting the orchestration layer each time. Cost tracking that told me we'd burned through $400 before the pipeline even finished its second run.

The agents were maybe 15% of my codebase. The infrastructure was the rest.

I looked at LangGraph, CrewAI, AutoGen, OpenAI Swarm. They're good at what they do. But none of them solved the full operating problem: routing + quality + cost + memory + execution topology + security, in one coherent system. So I built one.

The core insight: agents need what programs got

Programs got operating systems because running directly on hardware was unsustainable. You needed process scheduling, memory management, I/O abstraction, security isolation.

Agents have the same problem. When you're orchestrating 6 agents across 3 providers with different cost profiles, quality requirements, and failure modes — you need the same abstractions. Scheduling (which agent runs when, in what topology). Memory management (what context survives between sessions). I/O abstraction (HTTP, MCP, CLI, webhooks — agents shouldn't care). Security (credential vaults, PII sanitization, SSRF protection).

That analogy drove the architecture. Qualixar OS isn't a library you import. It's a runtime you start. Agents register with it, and it handles everything else.

What shipped in v2.2.0

Here are the concrete numbers. I'm listing these because I'm tired of agent framework launches that say "powerful" and "scalable" without showing what that means.

Execution topologies: 13 built-in patterns — sequential, parallel, hierarchical, DAG, debate, mesh, star, grid, forest, circular, mixture-of-agents, maker, and hybrid. You declare the topology, the system handles the execution semantics. Debate topology, for example, runs N agents on the same input and synthesizes the outputs through a judge.

Model routing: Cost-quality-latency constraint solver. You tell it "I need quality above 0.8, latency under 2 seconds, cost under $0.01 per call." It picks the model. When a provider goes down or changes pricing, routing adapts. Backed by a POMDP-based belief model (Forge AI) that can design agent teams automatically from a task description.

Judge pipeline: Multi-judge consensus with few-shot calibration, built on research from AgentAssert — our contract-based reliability testing framework (arXiv:2602.22302). Not "did the agent return a response" but "is this response actually correct, complete, and safe." Few-shot examples in the judge prompts reduced calibration drift significantly.

Memory: SLM-Lite cognitive memory, powered by SuperLocalMemory — backed by 3 peer-reviewed papers (arXiv:2604.04514, arXiv:2603.14588, arXiv:2603.02240). SQLite-backed, fully local. Episodic memory, semantic recall via embeddings (new in v2.2.0), working memory with decay. No cloud dependency. Your agent's memory stays on your machine.

Security: RBAC middleware on all enterprise routes. Credential vault with no plaintext exposure. PII sanitization in the output pipeline. SSRF protection on the new HTTP request tool. CSP headers. Request ID propagation for audit trails.

Communication: 7 channels — HTTP API, MCP protocol (native), CLI, Discord, Telegram, Webhook, Slack. Same agent, accessible from anywhere.

The boring stuff that matters: 2,936 tests across 213 test files. 761 source files, 161,810 lines. 852KB npm package. 25 CLI commands. 25 MCP tools. 24 dashboard tabs. 9 built-in tools. Native A2A protocol support. Programmatic API via createQosInstance(). Task execution streaming via SSE. Part of a research ecosystem with 7 peer-reviewed papers on arXiv.

Install it with npx qualixar-os.

The 7-perspective audit story

This is the part I'm most proud of, and it has nothing to do with writing code.

Before launch, I ran 7 independent AI agents (Claude Opus) against the entire codebase. Each agent got a different persona and a harsh audit prompt. Zero prior context about the repo. They'd never seen the code before. The perspectives:

Industry Architect — enterprise readiness, integration patterns
Agentic AI Specialist — framework design, agent orchestration
Academic Reviewer (PhD caliber) — algorithmic rigor, citation accuracy
Market Researcher — positioning, adoption barriers
Veteran AI/ML Architect (20 years hands-on) — production hardening
Competitive Intelligence — GitHub landscape analysis
Hardcore QA Tester — edge cases, failure modes, security

They came back with 154 raw findings. After deduplication, 76 unique issues.

The initial scores averaged 5.99 out of 10. Range: 5.0 to 7.05. They were brutal.

Some highlights of what they found:

RBAC middleware existed but wasn't wired to enterprise routes. Security theater.
The credential vault had a code path that could return plaintext secrets in an API response.
PII sanitization was implemented but not plugged into the chat output pipeline.
A race condition in the chat system: two concurrent messages to the same conversation could corrupt state because streams were keyed by conversation ID instead of message ID.
The README claimed framework adapter support that didn't match the actual source code.
Documentation called the strategy scoring system "RL Training" when it's actually weighted averaging — not reinforcement learning.
SSRF protection didn't exist on HTTP-based tools.

None of these would have shown up in unit tests. Every single one would have been a production incident.

We fixed all 76 findings. Not "addressed." Fixed. RBAC wired. Vault plaintext removed. PII sanitization plugged in. Race condition resolved. Claims corrected. SSRF protection added.

Then we re-audited. Post-fix scores averaged 7.76 out of 10 (range: 7.0 to 8.5). Five GO verdicts, one Minor Revisions, one Conditional-GO. Not perfect — the Academic Reviewer wanted more formal verification, and the Competitive Intelligence agent noted the FSL license and zero-star fresh repo as adoption risks. Both fair points.

I think this process — adversarial multi-perspective audit by independent AI agents before launch — should be standard practice. It cost me one evening and caught issues that would have taken months to surface through user reports.

What doesn't work well yet

I'd be lying if I called this production-ready for everyone. Here's what's rough:

Dashboard UX is functional, not polished. 24 tabs is a lot of surface area. Some tabs feel like developer tools, not user interfaces. The streaming visualization works but needs design attention.

Some topologies are less battle-tested than others. Sequential, parallel, and hierarchical get the most exercise. Grid and circular topologies exist and pass tests, but I haven't run them on demanding real-world workloads yet.

Documentation has gaps. 72+ files sounds like a lot until you realize the system has 761 source files. The three new tutorials cover the common paths. The uncommon paths — custom topology creation, extending the judge pipeline, writing your own memory providers — still need proper guides.

Tested mainly on macOS. I develop on a Mac. The test suite runs on macOS. Linux should work (it's Node.js), and Docker is available, but I haven't done exhaustive cross-platform testing.

Fresh repo, early community. There are no Stack Overflow answers yet, no community plugins. You'd be an early adopter, with everything that implies.

The data loss story

On March 24, 2026, a catastrophic rm -rf command deleted my entire home directory. All code. All projects. All memory systems. Everything.

I won't go into the details of how it happened. What matters is what happened next.

I had architecture documents — 47 design decisions, interface specifications, database schemas — that survived because they'd been synced to a different location. No code survived. Just the blueprints.

I rebuilt from those blueprints. The second version came out cleaner. When you lose everything and rebuild from architecture docs, you don't carry forward the accumulated technical debt. You don't preserve the workarounds from when you didn't understand the problem yet. You build what you now know you should have built the first time.

The irony isn't lost on me: a system designed to be the memory and runtime backbone for AI agents was itself rebuilt from memory. Architecture survived code.

It also made me paranoid about safety in ways that shaped the product. The filesystem sandbox, the credential vault, the PII sanitization — these aren't checkboxes. They're scars.

The technical choices, briefly

TypeScript + Node.js. I know Rust would be faster. I chose developer accessibility over raw performance. If you can write JavaScript, you can extend this system. The 852KB package size suggests the abstraction cost is reasonable.

SQLite for everything. Memory, configuration, marketplace registry, agent state. One dependency. No database server. Runs everywhere.

FSL-1.1 (Functional Source License). Source available, free for non-competing use, converts to Apache 2.0 after 2 years. I know this limits adoption compared to MIT. It's a conscious trade-off while the project is young.

MCP as a first-class protocol. Every tool, every agent capability is accessible via the Model Context Protocol. This means any MCP-compatible client (Claude, Cursor, and a growing ecosystem) can use Qualixar OS natively.

What I'd do differently

Start with the judge pipeline, not the orchestrator. I built execution topologies first because they were architecturally interesting. In practice, the judge pipeline is what makes agent output trustworthy. If I were starting over, quality evaluation would be day one.

Write the paper earlier. The arXiv paper (2604.06392) forced me to formalize my thinking and cite related work properly. Several architectural improvements came directly from writing the paper, not from writing the code.

Run the adversarial audit earlier. The 7-perspective audit found issues I'd been blind to for months. Running it before launch was good. Running it every month would have been better.

Try it

npx qualixar-os

That starts the runtime with the dashboard on port 3000. From there you can define agents, pick a topology, and run tasks — through the CLI, the HTTP API, or MCP.

The GitHub repo has the source, quickstart guide, and the full architecture. The arXiv paper (DOI: 10.5281/zenodo.19454219) has the formal treatment — and it's one of 7 papers across the Qualixar research ecosystem covering agent orchestration, reliability testing, memory, evaluation, and skill verification.

If you build agent systems and have opinions about what's missing, I want to hear them. File an issue, start a discussion, or just tell me what's broken. The 7 AI auditors found 76 things. I'm sure humans will find more.

Qualixar OS is open source under FSL-1.1 (converts to Apache 2.0 after 2 years). Built by a solo developer. Backed by 7 peer-reviewed papers across agent orchestration, reliability, memory, evaluation, and skill testing. Not funded, not affiliated with any company. Just trying to solve the agent infrastructure problem properly.

The Qualixar AI Agent Reliability Platform

SuperLocalMemory — persistent memory + learning for AI agents
Qualixar OS — universal agent runtime with 13 topologies
SLM Mesh — P2P coordination across AI sessions
SLM MCP Hub — federate 430+ MCP tools through one gateway
AgentAssay — token-efficient agent testing
AgentAssert — behavioral contracts + drift detection
SkillFortify — formal verification for agent skills

19K+ monthly downloads · 154 GitHub stars · zero cloud dependency.

Start here → qualixar.com

Run Multi-Agent Teams from Claude Code with Qualixar OS (25 MCP Tools)

varun pratap Bhardwaj — Fri, 17 Apr 2026 10:01:58 +0000

Run Multi-Agent Teams from Claude Code with Qualixar OS (25 MCP Tools)

Qualixar OS is an open-source agent orchestration runtime. You give it a task in plain English, and it designs a team of AI agents, picks a topology, runs them, and evaluates the output through an adversarial judge pipeline. It ships with 25 MCP tools, so you can drive the entire system from Claude Code without touching a browser.

This post walks through connecting Qualixar OS as an MCP server in Claude Code and using it to design, run, and evaluate a multi-agent code review team -- all from your terminal.

Installation

npx qualixar-os

That starts the server and opens the dashboard at localhost:3000/dashboard/. You can also install globally:

npm install -g qualixar-os
qos serve --dashboard --port 3000

Qualixar OS auto-detects Ollama for local inference. No API keys required to start. Add cloud providers (Anthropic, OpenAI, Azure, etc.) later through the Settings tab if you want more power.

MCP Server Configuration

Add this to your ~/.claude.json:

{
  "mcpServers": {
    "qualixar-os": {
      "command": "npx",
      "args": ["qualixar-os", "--mcp"]
    }
  }
}

Restart Claude Code. You now have 25 tools available. Run list tools in Claude Code to verify they appear.

The same config works in Cursor, Windsurf, VS Code (with MCP extension), or any MCP-compatible client.

The 25 MCP Tools

Tools are organized by domain. Here is the full catalog.

Task Execution

Tool	What it does
`run_task`	Submit a task. Forge AI auto-designs the agent team. Accepts optional `topology`, `budget_usd`, `mode`, and `simulate` (dry-run).
`get_status`	Poll task status by ID.
`list_tasks`	List recent tasks (most recent 50).
`pause_task`	Pause a running task.
`resume_task`	Resume a paused task.
`cancel_task`	Cancel a task.
`redirect_task`	Change a task's prompt mid-execution. Useful for steering agents without restarting.

Agents and Forge AI

Tool	What it does
`list_agents`	List all registered agents and their current state.
`list_topologies`	List the 13 available execution topologies (sequential, debate, hierarchical, etc.).
`get_forge_designs`	Retrieve the team designs Forge AI generated. Shows agent roles, tool assignments, topology selection, and estimated cost.

Quality and Memory

Tool	What it does
`get_judge_results`	Get structured evaluation results from the judge pipeline. Includes per-criterion scores, severity ratings, and improvement suggestions.
`search_memory`	Search SLM-Lite memory by query. Supports filtering by layer (episodic, semantic, procedural, behavioral) and result limits.
`get_rl_stats`	Get reinforcement learning stats -- which topologies perform best for which task types over time.

Chat and Data

Tool	What it does
`send_chat_message`	Send a message in a chat conversation (streaming via WebSocket on the dashboard side).
`list_connectors`	List configured data connectors.
`test_connector`	Test a connector's connection.
`list_datasets`	List available datasets.
`preview_dataset`	Preview rows from a dataset.
`search_vectors`	Search the vector store.

Blueprints and Prompts

Tool	What it does
`list_blueprints`	List saved agent blueprints.
`deploy_blueprint`	Deploy a blueprint as a running agent team.
`list_prompts`	List prompt templates.
`create_prompt`	Create a new prompt template.

System

Tool	What it does
`get_cost`	Cost breakdown -- per model, per agent, per task.
`get_system_config`	Current system configuration (providers, models, budget limits).

If you are on a tight context budget, Qualixar OS also offers 7 domain-grouped tools (qos_task, qos_system, qos_agents, qos_context, qos_quality, qos_workspace, qos_workflow_create) that pack the same 25 operations into fewer tool definitions using an action discriminator. Set QOS_TIER=core to expose only 2 tools (task + system), or QOS_TIER=extended for 4. Default is full.

Tutorial: Code Review Team via Forge AI

Here is a concrete walkthrough. You are in Claude Code, Qualixar OS is connected as an MCP server, and you want to run a multi-agent code review on a pull request.

Step 1: Submit the task

Call run_task with your prompt:

run_task({
  prompt: "Review the authentication module in src/auth/ for security vulnerabilities, code quality issues, and test coverage gaps. Produce a structured report.",
  type: "code",
  mode: "power"
})

Forge AI reads the prompt, decides this is a code quality task, and auto-designs a team.

Step 2: Inspect the Forge design

Call get_forge_designs to see what Forge created:

get_forge_designs({ taskType: "code" })

Forge might return something like:

3 agents: Security Analyst, Code Quality Reviewer, Test Coverage Auditor
Topology: Debate (two reviewers produce independent reports, a judge synthesizes)
Tools assigned: file_read, code_search, file_write
Estimated cost: $0.04

If you disagree with the topology, you can cancel and re-submit with an explicit override:

run_task({
  prompt: "...",
  topology: "hierarchical"
})

Step 3: Monitor execution

Poll status:

get_status({ taskId: "task_abc123" })

Status transitions: pending -> forge_designing -> executing -> judging -> completed (or rejected -> retry loop, up to 5 rounds).

Step 4: Check quality scores

Once execution completes, the judge pipeline runs automatically. Retrieve results:

get_judge_results({ taskId: "task_abc123" })

The judge returns structured feedback: per-criterion scores (correctness, completeness, clarity), an overall verdict (approved/rejected), severity ratings on any issues found, and specific improvement suggestions. If rejected, Forge automatically redesigns the team using the judge's feedback and re-executes -- up to 5 rounds, with a 3x budget cap as a safeguard.

Step 5: View in the dashboard

Open localhost:3000/dashboard/ to see the full execution visually. The 24-tab dashboard shows real-time agent activity (Swarms tab), judge verdicts (Judges tab), cost breakdown (Cost tab), and the final output (Chat tab). Everything you did from Claude Code is reflected there.

Advanced: Topology Selection and Cost Constraints

Choosing a topology

Qualixar OS supports 13 execution topologies. A few worth knowing:

Topology	When to use
`sequential`	Step-by-step pipelines where order matters
`parallel`	Independent analyses you want to run simultaneously
`debate`	When you want adversarial quality (two agents argue, judge decides)
`hierarchical`	Complex tasks that need decomposition into subtasks
`hybrid`	PII-sensitive work -- routes sensitive fields to local models, offloads the rest to cloud

Pass topology to run_task to override Forge's automatic selection.

Budget constraints

run_task({
  prompt: "...",
  budget_usd: 0.10
})

Forge respects the budget when selecting models and team size. Cost tracking is available during and after execution via get_cost.

Dry run

run_task({
  prompt: "...",
  simulate: true
})

Returns the Forge design and cost estimate without actually running agents.

A2A: Agent-to-Agent Protocol

Qualixar OS also implements the A2A protocol (v0.3). When the server is running, it exposes an agent card at:

GET http://localhost:3000/.well-known/agent-card

This means external A2A-compatible agents can discover and submit tasks to your Qualixar OS instance. Internal agents also communicate via A2A. Both MCP (tool calling from IDE) and A2A (agent-to-agent federation) work simultaneously on the same server.

The Qualixar AI Agent Reliability Platform

Seven open-source primitives. Seven peer-reviewed papers. One reliability platform.

SuperLocalMemory — persistent memory + learning for AI agents (16K+ monthly installs)
Qualixar OS — universal agent runtime with 13 topologies
SLM Mesh — P2P coordination across AI sessions
SLM MCP Hub — federate 430+ MCP tools through one gateway
AgentAssay — token-efficient agent testing
AgentAssert — behavioral contracts + drift detection
SkillFortify — formal verification for agent skills

Start here → qualixar.com

I Tracked Why AI Agent Projects Fail. 80% of the Time, It's Not the Agents.

varun pratap Bhardwaj — Fri, 17 Apr 2026 10:01:47 +0000

Last quarter, a team I advise at a Fortune 100 company built a multi-agent pipeline that could analyze SEC filings, cross-reference market data, and generate investment summaries. In the demo, it was stunning. GPT-4o handled reasoning. Claude did the writing. A custom agent orchestrated the flow.

They spent 3 weeks building the agents. They spent the next 14 weeks building everything around them.

Routing logic. Retry policies. Cost tracking. Quality checks. Memory that persisted between sessions. Logging that was actually searchable. A dashboard so the ops team could see what was happening without reading Python.

The agents were 18% of the codebase. The infrastructure was the other 82%.

This is not an isolated story. This is the story.

The numbers nobody talks about

Let's start with what's public:

Gartner (March 2025): 40% of agentic AI projects will be scaled back or cancelled by 2028. Not because agents are dumb — because teams can't operationalize them.
Gartner (2026): 1,445% surge in enterprise inquiries about multi-agent systems. Everyone wants to build them. Few know how to run them.
GitHub data: 4% of all GitHub commits now come from Claude Code alone — roughly 135,000 commits per day. Agents aren't experimental. They're writing production code right now.
Flowise AI (March 2026): A CVSS 10.0 remote code execution vulnerability hit 12,000+ deployed instances. When agent infrastructure is an afterthought, security is too.

The pattern is consistent: building agents is a solved problem. Operating agents is where projects die.

The five infrastructure problems every agent team solves from scratch

After 15 years in enterprise IT — and after building agent systems that actually shipped into production — I've watched the same five problems appear on every project. Different company, different use case, same headaches.

1. The routing problem

You have a pipeline with four agents. One needs speed (classification). One needs depth (analysis). One needs to be cheap (summarization). One needs multimodal understanding (document processing).

That's four different models, potentially four different providers, with different rate limits, latency profiles, and pricing.

Who decides which model serves which agent? Most teams hardcode it. Which works until your provider changes pricing, deprecates a model, or has an outage. Then someone rewrites routing logic at 2 AM.

What good looks like: Declarative routing constraints. "This agent needs latency under 2 seconds, quality above 0.8, cost under $0.01 per call." The system figures out the rest. When a provider goes down, traffic shifts automatically.

# What teams WANT to write
routing:
  analysis_agent:
    constraints:
      max_latency_ms: 2000
      min_quality: 0.8
      max_cost_per_call: 0.01
    fallback: [claude-3-haiku, gpt-4o-mini]

# What teams ACTUALLY write: 200 lines of this
if task_type == "analysis":
    try:
        response = openai_client.chat(model="gpt-4o", ...)
    except RateLimitError:
        try:
            response = anthropic_client.messages(model="claude-3-5-sonnet", ...)
        except Exception:
            response = openai_client.chat(model="gpt-4o-mini", ...)
            log.warning("Fell back to mini, quality may be degraded")

Every team writes that second version. Nobody wants to.

2. The quality problem

Agent output is non-deterministic. Same prompt, same model, Monday vs. Friday — different quality. This is fine in a chatbot. It's not fine when your agent is generating financial reports, writing customer communications, or making decisions that affect revenue.

Most teams discover this the hard way: a customer complains, someone traces it back to a hallucinated data point, and the response is "we should probably add eval."

What good looks like: A judge pipeline that runs automatically. Every agent output gets evaluated against configurable criteria before it reaches the user. Multiple judges can form consensus. Quality scores feed back into routing — agents that produce lower quality get routed less traffic.

Here's the uncomfortable truth: the teams that skip quality enforcement are the teams that end up in the 40% that get cancelled. Leadership loses trust when agent output is unpredictable.

3. The memory problem

Your agent solved a problem yesterday. Today, the same user asks a related question. Your agent starts from zero.

This isn't a vector database problem. Bolting RAG onto an agent gives it "search" — it doesn't give it "memory." Real cognitive memory has structure:

Working memory: What's relevant right now, in this conversation
Episodic memory: What happened in past interactions (the story)
Semantic memory: What things mean (the knowledge)
Procedural memory: How to do things (the skills)

Humans don't remember everything. We consolidate — important things get reinforced, irrelevant things fade. Agent memory should work the same way. Most agent memory implementations are append-only vector stores that grow until they're too slow to query and too noisy to be useful.

What good looks like: Local-first memory with automatic consolidation. The agent remembers what matters, forgets what doesn't, and retrieves what's relevant — without a round-trip to a cloud vector database.

4. The cost problem

Three agents running in parallel, each hitting a different model API. One retries four times because of a transient error. Another loops because its termination condition is slightly wrong.

Your daily budget just became your weekly budget. And nobody noticed until the invoice arrived.

What good looks like: Per-agent cost tracking, circuit breakers that kill runaway agents, budget caps that actually enforce. This isn't exotic — it's what every cloud service does for compute. Agent compute just doesn't have the tooling yet.

5. The observability problem

Something went wrong. An agent produced bad output three steps deep in a pipeline. 217 events fired. 47 tool calls. 12 LLM invocations across 3 providers.

Where do you start looking?

Most agent systems log everything or nothing. Either you have a 50MB log file per request with no structure, or you have print("agent finished") and a prayer.

What good looks like: Structured traces with causality. "This output was produced by Agent C, which received input from Agent B, which was routed to GPT-4o because Agent A's Claude request exceeded the latency budget." Every decision point, every tool call, every retry — traceable and searchable.

Why this isn't a framework problem

Frameworks are doing their job. CrewAI gives you role-based teams. LangGraph gives you stateful graphs. AutoGen gives you conversations. These are real, useful tools.

But they're solving the what — what agents do, how they reason, which tools they call.

The five problems above are the how of production operations. And they're framework-agnostic. Whether your agent is built with CrewAI or LangGraph or raw API calls, it still needs routing, quality enforcement, memory, cost control, and observability.

This is the Docker-to-Kubernetes gap. In 2013, Docker let you run a container. But running containers in production needed a layer above the runtime — scheduling, networking, scaling, health checks, recovery. That was Kubernetes. Container runtime was the capability. Kubernetes was the operations layer.

Agent frameworks are the capability. The operations layer is what's missing.

The topology dimension most teams miss

Beyond the five operational problems, there's a design problem that compounds everything: how agents communicate determines whether your system works.

Most teams default to sequential pipelines (A passes to B passes to C) or simple parallel execution (A, B, C run simultaneously, merge results). These cover maybe 20% of real-world multi-agent needs.

There are at least 12 distinct coordination patterns, and choosing the wrong one silently kills performance:

Pattern	When it wins	When it fails
Sequential	Strict ordering matters	Latency-sensitive tasks
Parallel	Independent analysis	Conflicting outputs need reconciliation
Hierarchical	Clear task decomposition	Boss agent decomposes poorly
DAG	Mixed dependencies	Complex failure handling
Debate	High-stakes decisions	Routine tasks (waste of tokens)
Mesh	3-5 agents collaborating	>5 agents (quadratic message growth)
Mixture-of-Agents	Quality-critical output	Cost-sensitive workloads
Circular	Iterative refinement	No termination condition = infinite loop

The architectural decision isn't just "which framework." It's "which communication pattern, for which sub-task, with which failure mode." Most teams pick one pattern for the whole system because switching patterns means rewriting the orchestration layer.

A checklist before you build

If you're about to build (or rebuild) a multi-agent system, here's what I'd verify before writing agent code:

[ ] Routing strategy defined. Do you know which model serves which agent, and what happens when that model is unavailable?
[ ] Quality gates in place. Is there a judge or eval step before agent output reaches users?
[ ] Memory architecture chosen. Are you using structured memory or just appending to a vector store?
[ ] Cost controls configured. Per-agent budgets, circuit breakers, retry limits?
[ ] Observability instrumented. Can you trace a bad output back to its root cause in under 5 minutes?
[ ] Topology selected intentionally. Did you pick your communication pattern, or did you default to sequential?
[ ] Framework lock-in assessed. Can you swap or add a new framework without rewriting your operations layer?

If four or more of these are "no" or "we'll figure it out later" — you're in the 40%.

What I'm building about it

I've spent the last several months working on this exact problem. Not a framework. An operations layer that sits above frameworks and handles routing, quality, cost, memory, and observability for any agent, from any framework.

It's called Qualixar OS. Here's the honest version:

What it does: Imports agents from CrewAI, LangGraph, AutoGen, and others through a bridge protocol. Routes tasks to models based on cost-quality-latency constraints. Runs a judge pipeline on agent output. Provides local-first cognitive memory (4-layer, with consolidation). Ships a 24-tab dashboard for operations teams. Supports 12 execution topologies with formal semantics.

Where it is: The core is solid — 2,831 tests, 49 database tables, 25 MCP tools. The paper is published and peer-reviewable. But this is an independent research project, not a VC-backed startup. I'm one researcher with 15 years of enterprise experience who got tired of watching teams rebuild the same infrastructure.

What it isn't: It's not a hosted service. It runs on your machine. It doesn't replace your agents or your framework. It's the layer underneath that you'd otherwise build yourself.

I wrote a 20-page paper formalizing the architecture, the topology algebra, and the execution semantics: arxiv.org/abs/2604.06392. Because claims without math are just marketing.

Try it:

npx qualixar-os

Or just read the paper first. If you've felt the pain described in this post, the architecture section will feel familiar — it's the infrastructure you already wished existed.

Paper: arxiv.org/abs/2604.06392
Project: qualixar.com

The Qualixar AI Agent Reliability Platform

Seven open-source primitives. Seven peer-reviewed papers. One reliability platform.

SuperLocalMemory — persistent memory + learning for AI agents (16K+ monthly installs)
Qualixar OS — universal agent runtime with 13 topologies
SLM Mesh — P2P coordination across AI sessions
SLM MCP Hub — federate 430+ MCP tools through one gateway
AgentAssay — token-efficient agent testing
AgentAssert — behavioral contracts + drift detection
SkillFortify — formal verification for agent skills

19K+ monthly downloads · 154 GitHub stars · zero cloud dependency.

Start here → qualixar.com

I'm Varun Pratap Bhardwaj — independent researcher, 15 years in enterprise IT. I build open tools for AI agent reliability. If you're dealing with the same infrastructure pain, I'd genuinely love to hear what's broken in your setup. The comments are open.

Your Multi-Agent System Probably Uses 1 Pattern. Here Are 12.

varun pratap Bhardwaj — Sun, 12 Apr 2026 13:34:20 +0000

Last month I watched a team burn $400 in API credits in a single afternoon.

They had four agents working on a research task. Each agent could see every other agent's output. Every time one agent updated its findings, the other three would re-process, generate new outputs, and trigger another round of updates. Four agents, talking to each other in a full mesh, with no termination condition. The token counter looked like a slot machine.

The fix took ten minutes. They didn't need a mesh. They needed a hierarchy — one coordinator agent that dispatched three specialists and merged the results. Same four agents, same task, same quality. One-eighth the cost.

The topology you choose for a multi-agent system — how agents communicate, who talks to whom, who decides — determines whether your system is fast or slow, reliable or brittle, cheap or expensive. Most teams default to chaining agents sequentially and never question it. But agent orchestration is a graph problem, and different tasks demand fundamentally different graph shapes.

I've spent the past year building and studying multi-agent architectures. Here are the 12 topology patterns that cover every coordination scenario I've encountered, grouped by complexity.

Simple Topologies

These are the building blocks. If you're new to multi-agent orchestration, start here.

1. Sequential

A ──▶ B ──▶ C ──▶ D

Each agent completes its work before passing output to the next. Classic pipeline.

When to use: Step-by-step workflows where order matters — document extraction, then classification, then summarization. Code generation, then review, then testing.

Example: An invoice processing pipeline where Agent A extracts line items from a PDF, Agent B validates amounts against a purchase order, Agent C flags discrepancies, and Agent D generates an approval recommendation. Each step needs the full output of the previous one.

Trade-off: Simple to reason about and debug. But slow — your total latency is the sum of every step. One slow agent blocks everything downstream.

2. Parallel

     ┌── A ──┐
     │       │
IN ──┼── B ──┼──▶ MERGE
     │       │
     └── C ──┘

All agents receive the same input and run simultaneously. Results merge at the end.

When to use: Independent analysis from multiple perspectives — sentiment analysis across languages, security scanning with different rule sets, researching a topic from multiple sources.

Example: Running a security audit, a performance profiler, and a code style linter on the same codebase simultaneously. Each analyzer is independent. Results merge into a single report. What took 90 seconds sequentially finishes in 30.

Trade-off: Dramatically faster than sequential when tasks are independent. But you need a merge strategy, and if agents produce conflicting outputs, the merge logic becomes the hard part.

Structured Topologies

These patterns impose hierarchy or dependency ordering. They handle complex, real-world workflows where "everything runs at once" isn't realistic.

3. Hierarchical

          BOSS
         / | \
        /  |  \
      W1  W2  W3

A supervisor agent decomposes a task and delegates sub-tasks to worker agents. Workers report back. The boss synthesizes.

When to use: Task decomposition — "write a research report" becomes "gather data" + "analyze trends" + "draft sections." Project management workflows where a lead agent coordinates specialists.

Example: A research agent receives "analyze the competitive landscape for AI agent frameworks." It spawns three workers: one searches academic papers, one crawls GitHub repos for stars and commit activity, one analyzes pricing pages. The boss merges findings into a structured competitive matrix.

Trade-off: Clean separation of concerns. The boss agent is a single point of failure, though — if it decomposes poorly, every worker goes in the wrong direction. Boss prompt quality is everything.

4. DAG (Directed Acyclic Graph)

A ──▶ B ──▶ D
 \         ▲
  └──▶ C ──┘

Agents form a dependency graph. An agent runs only when all its dependencies have completed. No cycles.

When to use: Complex workflows with mixed dependencies — data fetching (parallel) feeds into analysis (sequential) which feeds into report generation, but only after a separate validation step also completes.

Example: A CI/CD pipeline where linting and type-checking run in parallel after checkout, unit tests run after linting passes, integration tests wait for both unit tests and a database migration to complete, and deployment triggers only after every test is green.

Trade-off: Maximum flexibility and parallelism where the dependency structure allows it. The cost is complexity — you need a scheduler that understands the graph and handles failures mid-execution. This is the topology that build systems (Make, Bazel) have used for decades.

5. Star

      S1
      |
S4 ── HUB ── S2
      |
      S3

A central hub agent coordinates all communication. Spoke agents never talk to each other directly — everything routes through the hub.

When to use: Centralized coordination where you need one agent to maintain global state — a customer service router dispatching to specialist agents, or a planning agent that tracks progress across multiple workstreams.

Trade-off: Easy to monitor and control since all traffic flows through one point. But the hub is a bottleneck. If the coordinator agent is slow or hits rate limits, the entire system stalls.

6. Grid

A1 ── A2 ── A3
|     |     |
B1 ── B2 ── B3
|     |     |
C1 ── C2 ── C3

Agents are arranged in a matrix with structured communication along rows and columns. Each agent can communicate with its direct neighbors.

When to use: Structured team simulations — rows represent departments (engineering, design, QA) and columns represent features. Each agent has a specific role at a specific intersection.

Trade-off: Excellent for problems that naturally map to two dimensions. Rigid structure means it's overkill for simpler problems, and the communication overhead grows with grid size.

Collaborative Topologies

These patterns prioritize interaction quality over structural simplicity. Agents actively engage with each other's outputs.

7. Debate

PRO ◀──────▶ CON
      \   /
       ▼ ▼
      JUDGE

Two or more agents argue opposing positions. A judge agent evaluates the arguments and renders a decision.

When to use: High-stakes decisions where you need to stress-test reasoning — architecture decisions, risk assessments, legal analysis. Any situation where a single agent's confidence might mask a blind spot.

Example: An architecture decision record where one agent argues for microservices, another argues for a monolith, and a judge evaluates both against concrete constraints — team size, deployment frequency, latency budget. The judge doesn't just pick a winner; it synthesizes a recommendation with trade-offs acknowledged.

Trade-off: Produces higher-quality decisions by exposing weak arguments. Expensive in tokens — you're running 3+ agents on the same problem. Not worth it for routine tasks.

8. Mesh

A ◀──▶ B
|\ /|
| X  |
|/ \|
C ◀──▶ D

Every agent can communicate with every other agent. No hierarchy, no fixed paths.

When to use: Collaborative problem-solving where agents need to negotiate, share partial results, and build on each other's work — brainstorming sessions, collaborative writing, complex debugging where each agent sees a different part of the system.

Trade-off: Maximum flexibility and emergent collaboration. But message volume grows quadratically with agent count. Without careful protocol design, mesh systems devolve into noise. Works well with 3-5 agents; breaks down beyond that. This is the topology from my opening story — powerful, but easy to misuse.

9. Circular (Round-Robin)

A ──▶ B
▲     |
|     ▼
D ◀── C

Agents pass work around a ring, each refining or extending the previous agent's output. Multiple rounds.

When to use: Iterative refinement — draft, review, revise, polish. Translation chains where each pass improves quality. Red team / blue team cycles where attack and defense alternate.

Example: A writing pipeline where Agent A drafts, Agent B critiques for logical gaps, Agent C rewrites based on the critique, and Agent D fact-checks. The cycle repeats. Each round sharpens the output. After three rounds, the draft reads like it had a human editorial team.

Trade-off: Natural fit for refinement workflows. Quality improves with each round — up to a point. Diminishing returns kick in, and without a termination condition, the system loops forever. Always set a max-rounds limit.

10. Mixture-of-Agents

     ┌── A ──┐
     │       │
IN ──┼── B ──┼──▶ SYNTHESIZER ──▶ OUT
     │       │
     └── C ──┘

Multiple models (or the same model with different temperatures/prompts) process the same input. A dedicated synthesizer agent combines them into a single response that's better than any individual output.

When to use: Best-of-N generation — multiple agents draft answers, and a synthesizer picks the best parts of each. Content moderation where GPT-4, Claude, and Gemini each classify a piece of content, and majority voting catches edge cases any single model misses.

Trade-off: Consistently outperforms single-agent and simple-parallel approaches on quality benchmarks. The synthesizer is doing the hard intellectual work, though, so its prompt and capability matter enormously. Also 3-4x the token cost of a single agent.

Specialized Topologies

These patterns are purpose-built for specific domains.

11. Forest

   ROOT1         ROOT2
   / | \         / \
  A  B  C       D   E
    / \             |
   F   G            H

Multiple independent trees running in parallel. Each tree has its own hierarchy. No cross-tree communication until results merge at the end.

When to use: Parallel hierarchies — multiple teams working on separate features simultaneously, multi-repository analysis where each repo gets its own agent tree, running the same analysis against multiple datasets.

Trade-off: Scales linearly with the number of trees. Each tree is isolated, which is great for independence but means you can't share discoveries across trees mid-execution. Use this when the sub-problems are truly independent.

12. Maker (Build-Test-Ship)

ARCHITECT ──▶ BUILDER ──▶ TESTER ──▶ DEPLOYER
                 ▲            |
                 └── fix ─────┘

A specialized engineering pipeline with feedback loops. The builder creates, the tester validates, and failures loop back to the builder for fixes. Only passing work advances.

When to use: Software engineering workflows — code generation with automated testing, infrastructure-as-code with validation, any creative process where output quality must be verified before moving forward.

Example: A code generation workflow where the Maker agent writes a function and the Tester agent runs the test suite. Tests fail. The Tester sends the failure output and stack trace back to the Maker with instructions to fix. Two iterations later, all tests pass and the code advances to deployment.

Trade-off: Built-in quality gates mean output is more reliable than a straight pipeline. The feedback loop adds latency and cost, but catches errors before they propagate. The key design decision is how many retry cycles to allow before escalating.

Choosing the Right Topology

There's no universal best topology. The right choice depends on your constraints:

Constraint	Best Topologies
Minimize latency	Parallel, Forest, DAG
Maximize quality	Debate, Mixture-of-Agents, Circular
Minimize cost	Sequential, Star
Handle complex dependencies	DAG, Grid
Need iterative refinement	Circular, Maker
Collaboration-heavy	Mesh, Debate

Start with the simplest topology that fits your problem. Sequential until you need speed. Parallel until you need dependencies. DAG when Parallel gets tangled. Debate only when the decision is worth 3x the tokens. Mesh almost never — and when you do use it, set a message budget.

In practice, production systems compose topologies. A DAG might contain a Debate sub-graph at a critical decision node, with Parallel branches for independent analysis. The twelve patterns are composable primitives, not rigid choices.

One More Thing

All 12 topologies ship as composable primitives in Qualixar OS, with full execution semantics, retry policies, and observability built in. The formal definitions, message-passing protocols, and benchmark results are in the paper (arXiv:2604.06392).

DEMO

PORTAL WALKTHROUGH

I Tracked Why AI Agent Projects Fail. 80% of the Time, It's Not the Agents.

varun pratap Bhardwaj — Sun, 12 Apr 2026 11:54:59 +0000

They spent 3 weeks building the agents. They spent the next 14 weeks building everything around them.

The agents were 18% of the codebase. The infrastructure was the other 82%.

This is not an isolated story. This is the story.

The numbers nobody talks about

Let's start with what's public:

Gartner (March 2025): 40% of agentic AI projects will be scaled back or cancelled by 2028. Not because agents are dumb — because teams can't operationalize them.
Gartner (2026): 1,445% surge in enterprise inquiries about multi-agent systems. Everyone wants to build them. Few know how to run them.
GitHub data: 4% of all GitHub commits now come from Claude Code alone — roughly 135,000 commits per day. Agents aren't experimental. They're writing production code right now.
Flowise AI (March 2026): A CVSS 10.0 remote code execution vulnerability hit 12,000+ deployed instances. When agent infrastructure is an afterthought, security is too.

The pattern is consistent: building agents is a solved problem. Operating agents is where projects die.

The five infrastructure problems every agent team solves from scratch

1. The routing problem

You have a pipeline with four agents. One needs speed (classification). One needs depth (analysis). One needs to be cheap (summarization). One needs multimodal understanding (document processing).

That's four different models, potentially four different providers, with different rate limits, latency profiles, and pricing.

Who decides which model serves which agent? Most teams hardcode it. Which works until your provider changes pricing, deprecates a model, or has an outage. Then someone rewrites routing logic at 2 AM.

# What teams WANT to write
routing:
  analysis_agent:
    constraints:
      max_latency_ms: 2000
      min_quality: 0.8
      max_cost_per_call: 0.01
    fallback: [claude-3-haiku, gpt-4o-mini]

# What teams ACTUALLY write: 200 lines of this
if task_type == "analysis":
    try:
        response = openai_client.chat(model="gpt-4o", ...)
    except RateLimitError:
        try:
            response = anthropic_client.messages(model="claude-3-5-sonnet", ...)
        except Exception:
            response = openai_client.chat(model="gpt-4o-mini", ...)
            log.warning("Fell back to mini, quality may be degraded")

Every team writes that second version. Nobody wants to.

2. The quality problem

Most teams discover this the hard way: a customer complains, someone traces it back to a hallucinated data point, and the response is "we should probably add eval."

Here's the uncomfortable truth: the teams that skip quality enforcement are the teams that end up in the 40% that get cancelled. Leadership loses trust when agent output is unpredictable.

3. The memory problem

Your agent solved a problem yesterday. Today, the same user asks a related question. Your agent starts from zero.

This isn't a vector database problem. Bolting RAG onto an agent gives it "search" — it doesn't give it "memory." Real cognitive memory has structure:

Working memory: What's relevant right now, in this conversation
Episodic memory: What happened in past interactions (the story)
Semantic memory: What things mean (the knowledge)
Procedural memory: How to do things (the skills)

4. The cost problem

Three agents running in parallel, each hitting a different model API. One retries four times because of a transient error. Another loops because its termination condition is slightly wrong.

Your daily budget just became your weekly budget. And nobody noticed until the invoice arrived.

5. The observability problem

Something went wrong. An agent produced bad output three steps deep in a pipeline. 217 events fired. 47 tool calls. 12 LLM invocations across 3 providers.

Where do you start looking?

Most agent systems log everything or nothing. Either you have a 50MB log file per request with no structure, or you have print("agent finished") and a prayer.

Why this isn't a framework problem

Frameworks are doing their job. CrewAI gives you role-based teams. LangGraph gives you stateful graphs. AutoGen gives you conversations. These are real, useful tools.

But they're solving the what — what agents do, how they reason, which tools they call.

Agent frameworks are the capability. The operations layer is what's missing.

The topology dimension most teams miss

Beyond the five operational problems, there's a design problem that compounds everything: how agents communicate determines whether your system works.

Most teams default to sequential pipelines (A passes to B passes to C) or simple parallel execution (A, B, C run simultaneously, merge results). These cover maybe 20% of real-world multi-agent needs.

There are at least 12 distinct coordination patterns, and choosing the wrong one silently kills performance:

Pattern	When it wins	When it fails
Sequential	Strict ordering matters	Latency-sensitive tasks
Parallel	Independent analysis	Conflicting outputs need reconciliation
Hierarchical	Clear task decomposition	Boss agent decomposes poorly
DAG	Mixed dependencies	Complex failure handling
Debate	High-stakes decisions	Routine tasks (waste of tokens)
Mesh	3-5 agents collaborating	>5 agents (quadratic message growth)
Mixture-of-Agents	Quality-critical output	Cost-sensitive workloads
Circular	Iterative refinement	No termination condition = infinite loop

A checklist before you build

If you're about to build (or rebuild) a multi-agent system, here's what I'd verify before writing agent code:

[ ] Routing strategy defined. Do you know which model serves which agent, and what happens when that model is unavailable?
[ ] Quality gates in place. Is there a judge or eval step before agent output reaches users?
[ ] Memory architecture chosen. Are you using structured memory or just appending to a vector store?
[ ] Cost controls configured. Per-agent budgets, circuit breakers, retry limits?
[ ] Observability instrumented. Can you trace a bad output back to its root cause in under 5 minutes?
[ ] Topology selected intentionally. Did you pick your communication pattern, or did you default to sequential?
[ ] Framework lock-in assessed. Can you swap or add a new framework without rewriting your operations layer?

If four or more of these are "no" or "we'll figure it out later" — you're in the 40%.

What I'm building about it

It's called Qualixar OS. Here's the honest version:

What it isn't: It's not a hosted service. It runs on your machine. It doesn't replace your agents or your framework. It's the layer underneath that you'd otherwise build yourself.

I wrote a 20-page paper formalizing the architecture, the topology algebra, and the execution semantics: arxiv.org/abs/2604.06392. Because claims without math are just marketing.

Try it:

npx qualixar-os

Or just read the paper first. If you've felt the pain described in this post, the architecture section will feel familiar — it's the infrastructure you already wished existed.

Paper: arxiv.org/abs/2604.06392
Project: qualixar.com

Demo

I built a peer-to-peer communication layer for AI coding agents — here's how it works

varun pratap Bhardwaj — Wed, 08 Apr 2026 14:30:12 +0000

I run 3-4 AI coding sessions in parallel. Claude Code in VS Code for the frontend, another Claude session in the terminal for backend, sometimes Cursor or Antigravity for a third workstream.

The biggest pain point? They're completely isolated.

Session A refactors the authentication module. Session B starts editing the same file because it doesn't know Session A is working on it. I become the message bus — copy-pasting context between terminals like it's 2005.

This isn't unique to Claude Code or Cursor. Every AI coding agent has this problem. The Model Context Protocol (MCP) gives agents tools, but no way to coordinate with other agents on the same machine.

The Solution: SLM Mesh

SLM Mesh is an open-source MCP server that gives AI coding agents 8 tools for peer-to-peer communication:

Peer Discovery — agents auto-detect each other (scope by machine, directory, or git repo)
Direct Messaging — send structured messages between specific sessions
Broadcast — one-to-all message delivery
Shared State — key-value scratchpad accessible by all peers
File Locking — advisory locks with auto-expire to prevent edit conflicts
Event Bus — subscribe to peer_joined, state_changed, file_locked events
Summary — each agent announces what it's working on
Status — broker health and mesh statistics

Quick Start

# Install
npm install -g slm-mesh

# Add to Claude Code
claude mcp add --scope user slm-mesh -- npx slm-mesh

# Add to Cursor / VS Code / Windsurf
# mcp.json:
{
  "mcpServers": {
    "slm-mesh": {
      "command": "npx",
      "args": ["slm-mesh"]
    }
  }
}

That's it. Open two sessions and ask one of them to "check mesh_peers" — it will see the other.

Architecture

┌─────────────────────────────────────────────────┐
│                  Your Machine                    │
│                                                  │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐    │
│  │ Claude    │   │ Cursor   │   │ Aider    │    │
│  │ Code      │   │          │   │          │    │
│  └─────┬────┘   └─────┬────┘   └─────┬────┘    │
│        │              │              │           │
│  ┌─────┴────┐   ┌─────┴────┐   ┌─────┴────┐    │
│  │ MCP      │   │ MCP      │   │ MCP      │    │
│  │ Server   │   │ Server   │   │ Server   │    │
│  └─────┬────┘   └─────┬────┘   └─────┬────┘    │
│        │              │              │           │
│        └──────────────┼──────────────┘           │
│                       │                          │
│              ┌────────┴────────┐                 │
│              │ SLM Mesh Broker │                 │
│              │ localhost:7899  │                 │
│              │ SQLite + UDS    │                 │
│              └─────────────────┘                 │
└─────────────────────────────────────────────────┘

Key design decisions:

Auto-lifecycle: First MCP server auto-starts the broker. Last peer leaves, broker shuts down after 60s. No daemon to manage.
SQLite + WAL: Concurrent reads, single writer, crash-safe. Messages and events auto-pruned after 24/48 hours.
Unix Domain Sockets: Real-time push delivery in <100ms. No polling.
Bearer token auth: Random 32-byte token per broker session. No dangerous flags needed.
Agent-agnostic: Works with any MCP client. Auto-detects Claude Code, Cursor, Aider, Codex, Windsurf, VS Code.

Real-World Workflow

Here's what I actually do with it daily:

Morning (3 sessions):

Session 1 (VS Code): "I'm refactoring the auth module"
→ Sets summary via mesh_summary
→ Locks auth.ts via mesh_lock

Session 2 (Terminal): "What are the other sessions doing?"
→ Calls mesh_peers — sees Session 1 is on auth
→ Calls mesh_lock query auth.ts — sees it's locked
→ Works on database instead

Session 3 (Antigravity): Starts a migration
→ Broadcasts "database schema changing to v2.1" via mesh_send
→ Sets db_version = 2.1 in shared state via mesh_state
→ Sessions 1 and 2 see the update

No copy-pasting. No context switching. The agents coordinate themselves.

The Numbers

Metric	Value
Tests	480 passing
Coverage	100% lines
MCP tools	8
CLI commands	12
Dependencies	4 (MCP SDK, better-sqlite3, commander, zod)
Python client	Zero deps (stdlib only)
Install size	~80 KB (packed)

Comparison with claude-peers

claude-peers proved the demand for this — 1,600 stars in 2 weeks. SLM Mesh is the production-grade answer:

Feature	SLM Mesh	claude-peers
MCP tools	8	4
File locking	Yes	No
Shared state	Yes	No
Event bus	Yes	No
Agent-agnostic	Any MCP agent	Claude only
Dangerous flags	Not needed	Required
Tests	480 (100% cov)	0
Auth	Bearer token	None
Python client	Yes	No

Try It

npm install -g slm-mesh

GitHub: github.com/qualixar/slm-mesh
PyPI: pip install slm-mesh

MIT licensed. Part of the Qualixar research initiative by Varun Pratap Bhardwaj.

Feedback welcome — especially interested in what multi-session workflows you'd use this for.

SuperLocalMemory V3: Mathematical Foundations for Production-Grade Agent Memory

varun pratap Bhardwaj — Wed, 18 Mar 2026 04:00:44 +0000

[(https://varunpratap.com/blog/superlocalmemory-v3-mathematical-foundations)] We applied information geometry, algebraic topology, and stochastic dynamics to AI agent memory. 74.8% on LoCoMo with data staying local — the highest score reported without cloud dependency. 87.7% in full-power mode. 60.4% with no LLM at any stage. Open source under MIT.

The Problem Is Scale, Not Storage

Every AI coding assistant — Claude, Cursor, Copilot, ChatGPT — starts every session from scratch. The memory problem has been solved at development scale: Mem0, Zep, Letta, and others provide memory layers that work well for individual developers and small teams.

The unsolved problem is what happens at production scale.

At 10,000 memories, cosine similarity stops discriminating between relevant and irrelevant results. At 100,000 memories, contradictions accumulate silently — "Alice moved to London" and "Alice lives in Paris" coexist without detection. At enterprise scale, hardcoded lifecycle thresholds ("archive after 30 days") break because usage patterns vary across teams, projects, and domains.

And there is a regulatory dimension. The EU AI Act takes full effect August 2, 2026. Every memory system that sends data to cloud LLMs for core operations faces a compliance question that engineering alone cannot resolve — it requires an architectural answer.

We spent the last year applying mathematics to these problems.

Three Mathematical Techniques — Each a First in Agent Memory

1. Fisher-Rao Geodesic Distance (Retrieval)

Standard memory systems use cosine similarity. Cosine treats every embedding as equally confident — a memory accessed once scores identically to one accessed a thousand times, if their directions match.

We model each memory embedding as a diagonal Gaussian distribution with learned mean and variance. The Fisher-Rao geodesic distance — the natural metric on statistical manifolds — measures similarity along the curved surface of the probability space, not through flat Euclidean space.

In practice: memories that have been accessed more become more precise. Variance shrinks with repeated access via Bayesian conjugate updates. The system provably improves at finding things the more you use it.

At scale, this matters. When 10,000 memories compete for relevance, confidence-weighted distance provides discriminative power that flat cosine cannot.

Ablation: Removing Fisher-Rao drops multi-hop accuracy by 12 percentage points.

2. Sheaf Cohomology (Consistency)

Pairwise contradiction checking is O(n²) and misses transitive contradictions. At enterprise scale, it is both too slow and too weak.

We model the knowledge graph as a cellular sheaf — an algebraic structure from topology that assigns vector spaces to nodes and edges. Computing the first cohomology group H¹(G,F) reveals global inconsistencies from local data:

H¹ = 0 → All memories are globally consistent
H¹ ≠ 0 → Contradictions exist, even if every local pair looks fine

This scales algebraically, not quadratically. And it catches contradictions that no pairwise method can detect.

3. Riemannian Langevin Dynamics (Lifecycle)

Memory lifecycle management in current systems means hardcoded thresholds: "archive after 30 days," "promote after 10 accesses." These thresholds are tuned for average workloads and fail on everything else.

We replace thresholds with stochastic gradient flow on the Poincaré ball. The potential function encodes access frequency, trust score, and recency. The dynamics provably converge to a stationary distribution — the mathematically optimal allocation of memories across lifecycle states (Active → Warm → Cold → Archived).

No manual tuning. The system self-organizes based on actual usage patterns.

Results

Evaluated on the LoCoMo benchmark (Long Conversation Memory):

Configuration	Score	What It Means
Mode A Retrieval	74.8%	Data stays on your machine. Highest local-first score.
Mode C (Full Power)	87.7%	Cloud LLM at every layer. Comparable to industry systems.
Mode A Raw	60.4%	No LLM at any stage. First in the field.

For context — the competitive landscape:

System	Score	Cloud LLM Required
EverMemOS	92.3%	Yes
MemMachine	91.7%	Yes
Hindsight	89.6%	Yes
SLM V3 Mode C	87.7%	Yes (every layer)
Zep	~85%	Yes
SLM V3 Mode A	74.8%	No
Mem0	~58-66%	Yes
SLM V3 Mode A Raw	60.4%	No (zero-LLM)

The gap between Mode A Raw (60.4%) and Mode A Retrieval (74.8%) demonstrates that the four-channel mathematical retrieval pipeline captures the vast majority of benchmark requirements without any cloud dependency. The remaining gap between 74.8% and 87.7% is answer synthesis quality — not knowledge retrieval.

Why This Matters for Production

Current memory systems work at development scale. The mathematical foundations in V3 address three production-scale problems:

Retrieval quality at scale. Fisher-Rao provides discriminative power that cosine similarity loses when thousands of memories compete for relevance.
Consistency at scale. Sheaf cohomology detects contradictions algebraically, not quadratically. As knowledge graphs grow, this becomes the difference between reliable and unreliable memory.
Lifecycle at scale. Langevin dynamics self-organize memory allocation based on actual usage — no manual threshold tuning that breaks when workloads change.

These are not theoretical advantages. They are measurable on the benchmark, and they become more pronounced as memory count grows.

Three Operating Modes

V3 offers a privacy-accuracy spectrum:

Mode A: Local Guardian — All processing local. No cloud calls. EU AI Act compliant by architecture. 74.8% on LoCoMo.

Mode B: Smart Local — Mode A + local LLM via Ollama. Still fully private. No data leaves your machine.

Mode C: Full Power — Cloud LLM at every layer. 87.7% on LoCoMo. This is the configuration comparable to other memory systems. Data leaves the machine for processing.

The choice is yours. Switch anytime. Your memories stay consistent across all modes.

Getting Started

npm install -g superlocalmemory
slm setup
slm warmup    # Optional: pre-download embedding model
slm dashboard # 17-tab web dashboard at localhost:8765

Works with 17+ AI tools: Claude Code, Cursor, VS Code Copilot, Windsurf, ChatGPT Desktop, Gemini CLI, JetBrains, Zed, Continue, Cody, and more.

What We Believe

Current memory systems are impressive engineering. Every system in the competitive table represents meaningful work solving real problems for real users.

Our contribution is mathematical. We believe the future of agent memory is not more heuristics, but principled mathematics — techniques that provide guarantees, scale predictably, and can be adopted by any system.

The three techniques in V3 (Fisher-Rao, sheaf cohomology, Langevin dynamics) are not specific to our product. They are mathematical tools. We open-sourced everything under MIT because we believe the entire field benefits from mathematical foundations.

If these techniques make other memory systems better, we have succeeded.

Paper: Zenodo DOI: 10.5281/zenodo.19038659
Code: github.com/qualixar/superlocalmemory
Website: superlocalmemory.com

Varun Pratap Bhardwaj — Independent Researcher

Part of Qualixar

Part of Qualixar | Author: Varun Pratap Bhardwaj

5 AI Agent Memory Systems Compared: Mem0, Zep, Letta, Supermemory, SuperLocalMemory (2026 Benchmark Data)

varun pratap Bhardwaj — Wed, 18 Mar 2026 03:38:44 +0000

A factual comparison of the five most-referenced AI agent memory systems on architecture, LoCoMo benchmark scores, and EU AI Act compliance.

Why This Post Exists

Every comparison post I've read either reads like marketing for one system, or compares them on features without benchmark data. This is different: I'm the author of one of the systems (SuperLocalMemory), which means I have strong incentive to be honest — I can't be credibly wrong about the others without undermining my own credibility.

All scores are from published papers or official documentation. I've noted where scores vary across sources.

The Five Systems

System	Architecture	Creator	License	Status
Mem0	Cloud-hosted	Mem0 AI ($24M funded)	Open core	Production
Zep	Cloud-hosted + self-host	Getzep	Apache 2.0 + Commercial	Production
Letta (MemGPT)	Agent framework + LLM memory	Letta AI	Apache 2.0	Production
Supermemory	Cloud-hosted	Open source project	MIT	Production
SuperLocalMemory	Local-first mathematical	Independent research	MIT	Production

LoCoMo Benchmark Results

The LoCoMo benchmark (Long Conversation Memory) is the most widely cited evaluation for this space — 81 question-answer pairs across long multi-session conversations.

System	Score	Cloud LLM Required	Open Source
EverMemOS	92.3%	Yes	No
MemMachine	91.7%	Yes	No
Hindsight	89.6%	Yes	No
SLM V3 Mode C	87.7%	Yes (synthesis)	Yes (MIT)
Zep	~85%	Yes	Partial
Letta / MemGPT	~83.2%	Yes	Yes (Apache)
SLM V3 Mode A	74.8%	No	Yes (MIT)
Supermemory	~70%*	Yes	Yes (MIT)
Mem0 (self-reported)	~66%	Yes	Partial
SLM V3 Zero-LLM	60.4%	No LLM at all	Yes (MIT)
Mem0 (independent)	~58%	Yes	Partial

*Supermemory score estimated from limited published data.

Key takeaway: Every system requiring cloud LLMs clusters between 83-92%. SuperLocalMemory Mode A achieves 74.8% with zero cloud dependency — demonstrating that mathematical retrieval captures most of the benchmark value without cloud compute. Mode C reaches 87.7%, competitive with the top tier.

Architecture Comparison

Mem0

Model: Cloud-first, API-based. Memories stored on Mem0's servers.
Retrieval: Vector similarity over cloud embeddings (typically OpenAI).
Best for: Teams needing shared memory, managed infrastructure, cross-device access.
Limitation: Data sovereignty, offline use, EU AI Act compliance require additional work.

Zep

Model: Temporal knowledge graph hosted in cloud (or self-hosted Community Edition).
Retrieval: Graph-based temporal reasoning + semantic similarity.
Best for: Complex agent workflows requiring temporal entity relationships.
Limitation: Self-hosting requires infrastructure management; cloud version has same data locality issues as Mem0.

Letta (MemGPT)

Model: OS-inspired agent framework. LLM manages memory tiers (core context, recall, archival).
Retrieval: LLM-driven — the model decides what to retrieve and when.
Best for: Building agents where memory management logic needs to be customizable by the LLM.
Limitation: Requires LLM for all memory operations. Memory decisions inherit LLM opacity.

Supermemory

Model: Cloud-hosted with importable sources (tweets, web pages, documents).
Retrieval: Vector similarity + semantic search.
Best for: Personal knowledge management with multi-source ingestion.
Limitation: Cloud dependency; primarily designed for personal knowledge, not agent memory.

SuperLocalMemory V3

Model: Local-first with three mathematical retrieval layers.
Retrieval: 4-channel RRF fusion: Fisher-Rao geometric + BM25 lexical + entity graph + temporal.
Best for: Privacy-required workloads, EU AI Act compliance, individual developer memory, zero-cloud operation.
Limitation: Single-device by default; no native team sharing.

EU AI Act Compliance (Takes Effect August 2, 2026)

This dimension is increasingly important for enterprise deployment in the EU.

System	Mode A Compliance	Notes
SuperLocalMemory Mode A	✅ By architecture	Data never leaves device. Zero cloud calls.
All others	❌ Requires work	DPA required. Data sent to cloud providers.

SuperLocalMemory is the only system in this table that claims compliance-by-architecture. All others can achieve compliance through additional legal and technical measures, but require active work.

The Right Tool for the Job

None of these systems is "best." The right choice depends on your requirements:

Need team memory? → Mem0 or Zep. Both are designed for shared memory.

Need LLM to manage memory logic? → Letta. It's designed for LLM-driven memory management.

Need data sovereignty or EU AI Act compliance? → SuperLocalMemory Mode A. Only local-first provides this by architecture.

Need the highest benchmark score? → None of the open systems. EverMemOS/MemMachine/Hindsight score higher, but aren't open source.

Need open source + high score? → SuperLocalMemory Mode C (87.7%) or Letta (~83.2%).

Need zero cloud costs forever? → SuperLocalMemory Mode A. No API costs, no subscription.

My System (Full Disclosure)

I'm the author of SuperLocalMemory V3. I've tried to be factually accurate about all five systems. If I've gotten something wrong, open an issue on the repo or comment below.

Paper: arXiv:2603.14588
Code: github.com/qualixar/superlocalmemory
Website: superlocalmemory.com

Varun Pratap Bhardwaj — Independent Researcher
A Qualixar Research Initiative

SuperLocalMemory vs Mem0: When Zero-Cloud Beats Managed Memory (Benchmark Analysis)

varun pratap Bhardwaj — Wed, 18 Mar 2026 03:36:28 +0000

How a local-first system with mathematical foundations scores 74.8% on LoCoMo — higher than Mem0 — without a single cloud API call.

The Setup

I've spent the last year building SuperLocalMemory V3 — an open-source AI agent memory system that uses information geometry instead of cloud LLMs for core operations. Before I talk about how we compare, I want to be clear: this is not a hit piece on Mem0. They've built something genuinely useful with a great team. This is a factual benchmark analysis for developers choosing an architecture.

The key question: does local-first memory with mathematical foundations perform better than cloud-hosted managed memory?

On LoCoMo (Long Conversation Memory benchmark), the answer is yes.

The Numbers

System	LoCoMo Score	Cloud LLM Required	Cost
SLM V3 Mode C	87.7%	Yes (synthesis only)	$0 base (your API key)
SLM V3 Mode A	74.8%	No	$0 forever
Mem0 (self-reported)	~66%	Yes	Subscription
Mem0 (independent)	~58%	Yes	Subscription
SLM V3 Zero-LLM	60.4%	No LLM at all	$0

The headline: SLM Mode A (local-only) scores 74.8% — higher than Mem0's best-reported 66% — with data never leaving your machine.

A note on Mem0 scores: they vary across reports. Their self-reported number is ~66%, but independent measurements are closer to 58%. We cite both. Our scores are from our paper: arXiv:2603.14588.

Why Does Local Beat Cloud Here?

Mem0's architecture is straightforward: you send memories to their cloud, they store them, you query via API. It works well for team collaboration and managed infrastructure.

The weakness is retrieval quality. Standard cloud memory systems use cosine similarity over vector embeddings. At thousands of memories, cosine similarity stops discriminating well — everything starts looking similar.

We replaced cosine similarity with three mathematical techniques:

1. Fisher-Rao Geodesic Distance
Instead of treating each memory embedding as a point, we model it as a Gaussian distribution with a mean and variance. The Fisher-Rao distance measures similarity on the curved probability manifold — not through flat Euclidean space.

The key insight: memories accessed more often become more precise (variance shrinks via Bayesian updates). So frequently-relevant memories get geometrically closer to matching queries. Cosine can't do this.

Ablation: removing Fisher-Rao drops multi-hop accuracy by 12 percentage points.

2. Sheaf Cohomology for Consistency
Pairwise contradiction checking is O(n²) and misses transitive contradictions. Sheaf cohomology computes H¹(G, F) — a global consistency measure from local checks. Algebraic, not quadratic. Catches contradictions no pairwise method can.

3. Riemannian Langevin Dynamics for Lifecycle
Instead of "archive after 30 days," we use stochastic gradient flow on the Poincaré ball. The system self-organizes lifecycle states based on actual usage patterns. No manual threshold tuning.

Architecture Differences

Dimension	SLM Mode A	Mem0
Data location	On your device	Mem0's cloud
Embedding	Local model (nomic-embed-text)	OpenAI API
Retrieval	4-channel mathematical	Vector similarity
Offline	Full	None
API key needed	No	Yes
EU AI Act	Compliant by architecture	Requires DPA
Team memory	Single-device default	Native

When Mem0 Is Better

Honesty matters here. Mem0 wins on:

Team collaboration: Native multi-user shared memory. SLM is single-device by default.
Managed infrastructure: No local model to run, no disk usage, no maintenance.
Cross-device access: Memory follows you across devices natively.

If you're building a team-facing product where multiple users share memory, Mem0 is probably a better fit today.

When SLM Is Better

SLM wins when:

Data sovereignty is required: EU AI Act compliance, HIPAA-adjacent data, air-gapped environments.
Individual developer workflow: Personal coding assistant memory — Claude Code, Cursor, etc.
Zero ongoing cost: Mode A is free forever. No API costs, no subscription.
Offline operation: Mode A/B work with no internet connection.
Explainable retrieval: Every retrieval decision shows 4-channel scores. No black-box LLM.

Installing Both (30 seconds each)

# SuperLocalMemory
npm install -g superlocalmemory
slm setup
slm remember "Factoring auth into shared middleware on the payments service"
slm recall "payments auth"

# Mem0 (Python)
pip install mem0ai
# Then: set OPENAI_API_KEY and call mem0.add(), mem0.search()

Conclusion

The benchmark data is clear: local-first memory with information-geometric foundations outperforms cloud-hosted vector similarity on LoCoMo — by 8+ percentage points in the direct comparison, while requiring zero cloud infrastructure.

This matters because the AI memory field is mostly converging on "use a cloud LLM for everything." We're demonstrating a different path: mathematics as the intelligence layer, cloud as an optional enhancement.

Everything is MIT licensed and open source: github.com/qualixar/superlocalmemory

Paper: arXiv:2603.14588

Varun Pratap Bhardwaj — Independent Researcher
A Qualixar Research Initiative

I Added Persistent Memory to Claude Code in 60 Seconds (and It Actually Works)

varun pratap Bhardwaj — Wed, 18 Mar 2026 03:34:25 +0000

Claude Code forgets everything between sessions. Here's how I fixed it with one command and a local database that never leaves my machine.

The Problem

If you use Claude Code daily, you've felt this: every session starts from zero. You re-explain your codebase architecture. You remind it which patterns you prefer. You tell it again that you use uv not pip. Again. Every. Single. Session.

Claude Code is exceptional at reasoning within a session. Across sessions, it has no memory at all.

I built SuperLocalMemory to fix this. Here's the 60-second setup.

Setup (One Command)

npm install -g superlocalmemory
slm setup

That's it. slm setup downloads the embedding model (~275MB, one-time), initializes the local database, and registers the MCP server. Everything runs on your machine — no API keys, no cloud, no accounts.

Connect to Claude Code

Add to your Claude Code MCP config (~/.claude/settings.json or via the UI):

{
  "mcpServers": {
    "superlocalmemory": {
      "command": "slm",
      "args": ["mcp"]
    }
  }
}

Restart Claude Code. You'll see SuperLocalMemory tools appear in the toolbar.

Start Using It

The workflow is simple: tell Claude what to remember, ask it to recall later.

You: slm remember "This project uses uv not pip. Always use uv run python."
Claude: ✓ Stored memory about package manager preference.

[Next session, next week]

You: What package manager does this project use?
Claude: [calls slm recall] Based on your stored preferences: this project uses uv, not pip.

Or use the CLI directly:

# Remember something
slm remember "Auth is handled in middleware/auth.py — JWT, 24h expiry"

# Recall anything
slm recall "where is auth handled"

# See all memories
slm list

# Open the 17-tab dashboard
slm dashboard

What Actually Gets Stored

Claude Code can call the memory tools autonomously as it works. Common patterns that work well:

Project context:

slm remember "Monorepo: packages/api (FastAPI), packages/web (Next.js 15), packages/worker (Celery)"
slm remember "Production: Railway (API + worker), Vercel (web), Upstash Redis"
slm remember "Database: Supabase Postgres. Migrations with Alembic."

Preferences:

slm remember "Always use type hints. Prefer dataclasses over plain dicts."
slm remember "Test with pytest. Use pytest-asyncio for async tests. 80% coverage minimum."
slm remember "No print statements in production code — use structlog."

Decisions:

slm remember "Decided against GraphQL — REST is simpler for this use case (March 2026)"
slm remember "Payment processing uses Stripe not Paddle — existing contracts"

Bugs and fixes:

slm remember "Fixed: celery worker crashes if Redis connection drops during task — added retry with exponential backoff"

The Dashboard

slm dashboard

Opens a 17-tab web UI at localhost:8765. The tabs I use most:

Memories — browse all stored facts, edit or delete inline
Recall Lab — test queries before using in code sessions
Knowledge Graph — visual map of entities and relationships
Trust Dashboard — Bayesian trust scores per memory source

How It Actually Works (For the Curious)

Standard memory systems use cosine similarity over embeddings — it works but degrades at scale. SuperLocalMemory uses three mathematical techniques from our research paper:

Fisher-Rao geodesic distance — models each memory as a Gaussian distribution, not a point. Frequently accessed memories become more precise (variance shrinks via Bayesian updates). The result: the system gets better at finding things the more you use it.

Sheaf cohomology — detects contradictory memories globally, not just pairwise. If you've stored conflicting facts ("Auth uses JWT" and "Auth uses sessions"), the system surfaces the conflict.

Langevin dynamics — self-organizes memory lifecycle based on actual usage. Frequently accessed memories stay active; stale ones archive automatically.

On the LoCoMo benchmark, this approach achieves 74.8% accuracy with data staying fully local — higher than Mem0's 58-66% while requiring zero cloud dependency.

Three Modes

By default you get Mode A (fully local, no cloud):

slm mode a   # Default — zero cloud, 74.8% on LoCoMo
slm mode b   # + local Ollama LLM for synthesis (still private)
slm mode c   # + cloud LLM for synthesis (87.7% on LoCoMo)

I use Mode A. It's fast (sub-millisecond retrieval), private, and works offline. I switch to Mode B when I want the Ollama-powered cluster summaries in the dashboard.

Works With More Than Claude Code

The same memory layer works with every AI tool that supports MCP:

Cursor — add the same MCP config to Cursor settings
VS Code Copilot — via Continue.dev extension
Windsurf, Zed, JetBrains AI — same config
ChatGPT Desktop — via MCP bridge

One memory store, all your tools.

MIT License, Fully Open Source

npm install -g superlocalmemory   # npm
pip install superlocalmemory      # Python

GitHub: github.com/qualixar/superlocalmemory
Website: superlocalmemory.com
Paper: arXiv:2603.14588

1400+ tests. No telemetry. No accounts. Data never leaves your machine in Mode A.

Varun Pratap Bhardwaj — Independent Researcher
A Qualixar Research Initiative

Agentic Engineering Patterns: Architectural Building Blocks for AI Agent Systems

varun pratap Bhardwaj — Fri, 06 Mar 2026 06:55:25 +0000

Building an AI agent is not the same as calling an LLM in a loop. The moment you need an agent to use tools, remember past interactions, revise its own plans, or collaborate with other agents, you enter the domain of systems architecture. The patterns you choose — how the agent reasons, when it retrieves context, how it delegates — determine whether your system is reliable or a stochastic mess. This post breaks down the core architectural patterns that have emerged in agentic AI engineering, explains when each one applies, and shows you how memory layers tie them all together.

What You Will Learn

The four foundational agentic patterns: ReAct, Plan-and-Execute, Reflection, and Delegation

How each pattern structures the loop between reasoning, action, and observation

Where memory (short-term, long-term, episodic) fits into each pattern

Concrete Python code implementing each pattern with persistent memory retrieval

Trade-offs and failure modes so you know when not to use a given pattern

Conceptual Foundation: What Makes a System "Agentic"

An LLM call is stateless. You send a prompt, you get a completion. An agent, by contrast, operates in a loop: it perceives its environment, decides on an action, executes that action, observes the result, and feeds that observation back into its next decision. This loop is the defining characteristic.

Three capabilities distinguish an agent from a simple chain:

Tool use — the agent can invoke external functions (search, databases, APIs, code execution).
State management — the agent maintains context across multiple steps, including across sessions.
Autonomous decision-making — the agent decides what to do next without human intervention at each step.

The patterns we will examine are different ways of structuring this loop. None of them is universally superior. Each makes a trade-off between autonomy, reliability, latency, and cost.

graph TD
    subgraph "Agentic Loop"
        A[User Query] --> B[Reasoning / Planning]
        B --> C{Select Action}
        C -->|Tool Call| D[Execute Tool]
        C -->|Respond| H[Final Answer]
        D --> E[Observation / Result]
        E --> F[Memory Write]
        F --> B
    end

    subgraph "Memory Layer"
        G[Short-Term Memory<br/>Current conversation] -.-> B
        I[Long-Term Memory<br/>Past sessions, facts] -.-> B
        J[Episodic Memory<br/>Past task outcomes] -.-> B
        F --> G
        F --> I
        F --> J
    end

    style B fill:#4a90d9,color:#fff
    style F fill:#d9a34a,color:#fff

This diagram shows the general shape. Every pattern we discuss is a specific instantiation of this loop with different control flow decisions at the "Reasoning / Planning" and "Select Action" nodes.

Pattern 1: ReAct (Reason + Act)

ReAct, introduced by Yao et al. (2023), interleaves reasoning traces with actions. At each step, the agent produces a Thought (natural language reasoning), then an Action (tool invocation), then receives an Observation (tool output). This cycle repeats until the agent has enough information to produce a final answer.

ReAct is the simplest agentic pattern and the one you should reach for first.

1. The agent receives a query and generates a Thought

The thought is an explicit reasoning trace: "I need to find the current stock price of AAPL. I should use the stock_price tool."

2. The agent selects and invokes a tool (Action)

Based on the thought, the agent emits a structured action: stock_price(symbol="AAPL").

3. The tool returns a result (Observation)

The tool returns {"price": 187.42, "currency": "USD"}. This is appended to the agent's context.

4. The loop repeats or the agent responds

The agent decides whether it has enough information. If yes, it produces a final answer. If not, it generates another Thought and continues.

Here is a minimal ReAct implementation:

import openai
import json

# Define available tools
TOOLS = {
    "search": lambda query: f"Results for '{query}': [Wikipedia article about {query}]",
    "calculate": lambda expr: str(eval(expr)),  # simplified; use a sandbox in production
}

TOOL_DESCRIPTIONS = """
Available tools:
- search(query: str) -> str: Search the web for information
- calculate(expr: str) -> str: Evaluate a math expression
"""

def react_agent(query: str, max_steps: int = 5) -> str:
    """A minimal ReAct agent loop."""
    messages = [
        {"role": "system", "content": f"""You are a ReAct agent. For each step:
1. Thought: reason about what to do next
2. Action: call a tool using JSON: {{"tool": "name", "args": {{"key": "value"}}}}
3. When ready, respond with: {{"answer": "your final answer"}}
{TOOL_DESCRIPTIONS}"""},
        {"role": "user", "content": query},
    ]

    for step in range(max_steps):
        response = openai.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            temperature=0,
        )
        content = response.choices[0].message.content
        messages.append({"role": "assistant", "content": content})

        # Try to parse the agent's output as JSON
        try:
            parsed = json.loads(content)
        except json.JSONDecodeError:
            # If it's not JSON, treat it as the final answer
            return content

        if "answer" in parsed:
            return parsed["answer"]

        if "tool" in parsed:
            tool_name = parsed["tool"]
            tool_args = parsed.get("args", {})
            # Execute the tool
            observation = TOOLS[tool_name](**tool_args)
            # Feed observation back into the loop
            messages.append({
                "role": "user",
                "content": f"Observation: {observation}"
            })

    return "Max steps reached without a final answer."

# Usage
result = react_agent("What is the population of France divided by 3?")
print(result)

When to use ReAct: When your task requires interleaving information gathering with reasoning. It works well for question answering, research tasks, and data lookups where the agent needs 2-5 tool calls.

When not to use it: When the task requires a long-horizon plan with 10+ steps. ReAct is greedy — it decides one step at a time, which can lead to wandering.

Pattern 2: Plan-and-Execute

Plan-and-Execute separates planning from execution. First, the agent creates an explicit multi-step plan. Then a separate execution loop carries out each step. After execution, the agent can optionally revise the plan based on what it learned.

This pattern is better suited for complex tasks because the planning step forces the agent to commit to a strategy before spending tokens and tool calls on execution.

import openai
import json

def plan_and_execute(query: str) -> str:
    """Plan-and-Execute pattern: create a plan, then execute each step."""

    # Phase 1: Generate a plan
    plan_response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": """Create a step-by-step plan to answer the user's query.
Return a JSON array of step strings. Example: ["Step 1: ...", "Step 2: ..."]
Each step should be a concrete, actionable instruction."""},
            {"role": "user", "content": query},
        ],
        temperature=0,
    )
    plan = json.loads(plan_response.choices[0].message.content)
    print(f"Plan: {plan}")

    # Phase 2: Execute each step
    context = ""  # Accumulates results from previous steps
    for i, step in enumerate(plan):
        exec_response = openai.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": f"""You are executing step {i+1} of a plan.
Previous context: {context}
Execute this step and return the result."""},
                {"role": "user", "content": step},
            ],
            temperature=0,
        )
        step_result = exec_response.choices[0].message.content
        context += f"\nStep {i+1} result: {step_result}"

    # Phase 3: Synthesize final answer
    final_response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Synthesize a final answer from the execution results."},
            {"role": "user", "content": f"Original query: {query}\n\nExecution results:{context}"},
        ],
        temperature=0,
    )
    return final_response.choices[0].message.content

The key insight: by separating planning from execution, you can use different models for each phase (a stronger model for planning, a cheaper one for execution), and you can checkpoint and resume the plan.

Pattern 3: Reflection

Reflection adds a self-critique step. After the agent produces an output, a second pass evaluates that output for correctness, completeness, and adherence to instructions. If the evaluation fails, the agent revises its output.

This is not a standalone pattern — it layers on top of ReAct or Plan-and-Execute.

def reflect_and_revise(query: str, max_revisions: int = 2) -> str:
    """Generate an answer, then reflect on it and revise if needed."""

    # Initial generation
    draft = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Answer the user's question thoroughly."},
            {"role": "user", "content": query},
        ],
    ).choices[0].message.content

    for revision in range(max_revisions):
        # Reflection step: critique the draft
        critique = openai.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": """Critique the following answer.
Identify factual errors, missing information, or logical gaps.
If the answer is satisfactory, respond with exactly: APPROVED
Otherwise, list the specific issues."""},
                {"role": "user", "content": f"Query: {query}\n\nAnswer: {draft}"},
            ],
        ).choices[0].message.content

        if "APPROVED" in critique:
            return draft

        # Revision step: fix the issues
        draft = openai.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": "Revise the answer based on the critique."},
                {"role": "user", "content": f"Original query: {query}\n\nDraft: {draft}\n\nCritique: {critique}"},
            ],
        ).choices[0].message.content

    return draft

Reflection Can Be Wasteful

Reflection doubles (or triples) your LLM calls. Do not apply it to every agent response. Reserve it for high-stakes outputs: generated code that will be executed, answers to complex multi-step questions, or content that will be published. For simple lookups, reflection adds cost without meaningful quality improvement.

Pattern 4: Delegation (Multi-Agent Coordination)

Delegation splits a complex task across specialized agents. A supervisor agent breaks the task into subtasks and routes each to a specialist agent — a coder, a researcher, a data analyst. Each specialist has its own tools, system prompt, and potentially its own memory context.

def supervisor_agent(query: str) -> str:
    """A supervisor that delegates to specialist agents."""

    # Decide which specialists to invoke
    routing = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": """You are a supervisor agent.
Available specialists: ["researcher", "coder", "analyst"]
Given a query, return a JSON plan:
[{"agent": "researcher", "task": "..."}, {"agent": "coder", "task": "..."}]"""},
            {"role": "user", "content": query},
        ],
    ).choices[0].message.content

    subtasks = json.loads(routing)
    results = {}

    for subtask in subtasks:
        agent_name = subtask["agent"]
        task = subtask["task"]
        # Each specialist has a different system prompt and tool set
        specialist_result = run_specialist(agent_name, task, context=results)
        results[agent_name] = specialist_result

    # Synthesize results
    synthesis = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Combine the specialist results into a final answer."},
            {"role": "user", "content": f"Query: {query}\nResults: {json.dumps(results)}"},
        ],
    ).choices[0].message.content
    return synthesis

def run_specialist(name: str, task: str, context: dict) -> str:
    """Run a specialist agent with its own system prompt."""
    prompts = {
        "researcher": "You are a research agent. Find factual information.",
        "coder": "You are a coding agent. Write correct, tested code.",
        "analyst": "You are a data analyst. Interpret data and produce insights.",
    }
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": prompts[name]},
            {"role": "user", "content": f"Task: {task}\nContext from other agents: {json.dumps(context)}"},
        ],
    )
    return response.choices[0].message.content

The hard part of delegation is not the routing — it is shared state. When the coder agent needs context from the researcher agent, how does it get it? Passing everything in the prompt works at small scale but breaks down quickly. This is where memory becomes critical.

How Memory Ties These Patterns Together

Every pattern above has a shared weakness: context management. ReAct accumulates observations in its message history. Plan-and-Execute passes results between steps as text. Delegation passes context between agents as JSON blobs. None of these approaches scale beyond a single session.

Memory solves this by providing a persistent, queryable store that any agent (or any step within an agent) can read from and write to.

There are three memory layers:

Memory Type	Scope	Lifetime	Example
Short-term	Current task/session	Minutes to hours	Conversation history, intermediate results
Long-term	Cross-session	Days to permanent	User preferences, learned facts, past decisions
Episodic	Per-task	Permanent	"Last time I tried approach X, it failed because Y"

Here is how memory integrates into a ReAct agent:

import numpy as np

class AgentMemory:
    """A simple vector-based memory store for agent state."""

    def __init__(self):
        self.entries = []  # List of {"text": str, "embedding": list, "metadata": dict}

    def store(self, text: str, metadata: dict = None):
        """Store a memory entry with its embedding."""
        embedding = get_embedding(text)  # Your embedding function
        self.entries.append({
            "text": text,
            "embedding": embedding,
            "metadata": metadata or {},
        })

    def retrieve(self, query: str, top_k: int = 3) -> list[str]:
        """Retrieve the most relevant memories for a query."""
        query_embedding = get_embedding(query)
        scored = []
        for entry in self.entries:
            # Cosine similarity
            sim = np.dot(query_embedding, entry["embedding"]) / (
                np.linalg.norm(query_embedding) * np.linalg.norm(entry["embedding"])
            )
            scored.append((sim, entry["text"]))
        scored.sort(reverse=True, key=lambda x: x[0])
        return [text for _, text in scored[:top_k]]

def react_agent_with_memory(query: str, memory: AgentMemory, max_steps: int = 5) -> str:
    """ReAct agent augmented with persistent memory retrieval."""

    # Retrieve relevant past memories before starting
    relevant_memories = memory.retrieve(query, top_k=3)
    memory_context = "\n".join(f"- {m}" for m in relevant_memories) if relevant_memories else "None"

    messages = [
        {"role": "system", "content": f"""You are a ReAct agent with access to memory.
Relevant memories from past sessions:
{memory_context}

Use these memories to avoid repeating past mistakes and to build on prior knowledge.
Follow the Thought -> Action -> Observation loop."""},
        {"role": "user", "content": query},
    ]

    # ... standard ReAct loop from earlier ...
    final_answer = run_react_loop(messages, max_steps)

    # Store the outcome as episodic memory
    memory.store(
        f"Task: {query} | Outcome: {final_answer}",
        metadata={"type": "episodic", "task": query}
    )

    return final_answer

The critical detail: memory retrieval happens before the agent starts reasoning, and memory storage happens after the agent finishes. This creates a learning loop where each task execution improves future performance.

Seeing This in Practice

Multi-agent delegation introduces a harder memory problem: trust scoring. When Agent B retrieves a memory that Agent A wrote, how much should it trust that memory? If Agent A's task failed, its stored observations might be misleading.

SuperLocalMemory implements a local agent memory layer with hybrid search (combining vector similarity and keyword matching) that addresses this. It exposes a straightforward API for storing memories with metadata — including agent identity and task outcomes — and retrieving them with configurable scoring:

from superlocalmemory import MemoryStore

store = MemoryStore(path="./agent_memories")

# Agent A stores a research finding
store.add(
    text="The API rate limit for service X is 100 requests/minute as of March 2026.",
    metadata={
        "agent": "researcher",
        "task_id": "task-42",
        "task_outcome": "success",
        "confidence": 0.95,
    }
)

# Agent B (coder) retrieves relevant context, filtered by trust
results = store.search(
    query="rate limits for service X",
    top_k=5,
    filters={"task_outcome": "success"},  # Only trust successful task memories
)

for result in results:
    print(f"[{result.metadata['agent']}] {result.text} (score: {result.score:.3f})")

The hybrid search combines dense vector retrieval with sparse keyword matching, which matters in agentic contexts where queries often contain specific identifiers (API names, error codes) that pure semantic search can miss. You can inspect the full implementation in the GitHub repository to see how the scoring and filtering work under the hood.

Real-World Considerations

The Abstraction Trap

A recurring concern in the developer community — highlighted in discussions like "The Abstraction Trap: Why Layers Are Lobotomizing Your Model" — is that adding too many layers between the LLM and the task degrades performance. Every abstraction layer (planner, reflector, memory retrieval, routing) adds latency and potential error. Start with the simplest pattern (ReAct) and add complexity only when you have evidence that it helps.

Cost. A single ReAct loop with 4 steps costs 4 LLM calls. Add reflection and that doubles to 8. Add a planner and you are at 9+. Delegation multiplies this by the number of agents. Profile your token usage early.

Debugging. Agentic systems are hard to debug because the LLM's reasoning is non-deterministic. Log every step: the full prompt, the model's response, the tool inputs and outputs, and the memory retrievals. Without these logs, you are flying blind.

Failure modes by pattern:

ReAct: gets stuck in loops, calls the same tool repeatedly with slightly different arguments
Plan-and-Execute: creates plans that are too rigid or too vague; early step failures cascade
Reflection: the critic always finds something to complain about, causing infinite revision loops (always cap revision count)
Delegation: specialists produce incompatible outputs; the supervisor cannot reconcile them

Tool Execution Safety

If your agent can execute code or write to databases, sandbox it. A ReAct agent calling eval() on untrusted expressions — as in our simplified example above — is a remote code execution vulnerability. Use containers, restricted interpreters (like asteval), or separate execution environments with strict timeouts and resource limits.

Choosing the Right Pattern

Pattern	Best For	Steps	LLM Calls	Complexity
ReAct	Simple tool-use, Q&A	2-5	Low	Low
Plan-and-Execute	Multi-step tasks, research	5-15	Medium	Medium
Reflection	High-stakes outputs	+1-2 per cycle	Medium-High	Medium
Delegation	Complex tasks needing specialization	Varies	High	High

A practical heuristic: start with ReAct. If you find the agent wandering or failing on tasks that require more than 5 steps, move to Plan-and-Execute. If output quality matters more than speed, add Reflection. If the task genuinely requires different expertise domains, use Delegation.

These patterns also compose. A delegation supervisor can use Plan-and-Execute for routing, while each specialist uses ReAct internally, and the final synthesis uses Reflection. The architecture is modular by design.

Universal Memory Layer Architecture for AI Agents

varun pratap Bhardwaj — Thu, 05 Mar 2026 06:57:50 +0000

Most AI agents today are stateless. They receive a prompt, generate a response, and forget everything. If you have built anything with an LLM, you have felt this limitation firsthand: your agent cannot recall what happened two conversations ago, cannot learn from its mistakes, and cannot share context with other agents in your system. The context window is not memory. It is a scratchpad that gets wiped clean. To build agents that genuinely improve over time, you need a dedicated memory layer — one that persists knowledge, organizes it for fast retrieval, and works across multiple agents without coupling them together.

This post walks you through the architecture of such a memory layer from first principles. No handwaving, no black boxes. By the end, you will understand the design decisions behind memory persistence for AI agents and have runnable code you can adapt for your own systems.

What You Will Learn

The difference between episodic and semantic memory in agent systems, and when to use each.

How to design an interoperable memory schema that works across multi-agent architectures.

How hybrid search (vector + keyword + graph) enables efficient memory recall at scale.

Concrete implementation patterns in Python with working code examples.

Trade-offs and failure modes you will encounter in production.

Why Agents Need a Memory Layer

An LLM's context window is finite. GPT-4 Turbo offers 128K tokens; Claude gives you 200K. That sounds like a lot until your agent has been running for days, processing hundreds of tasks, accumulating observations, and collaborating with other agents. You cannot stuff all of that into a single prompt.

More importantly, a context window is ephemeral. When the session ends, the context is gone. Your agent starts from zero next time. This is the equivalent of a developer who loses all their notes every time they close their laptop.

A memory layer solves this by acting as persistent, queryable storage that sits outside the LLM. The agent writes to it during execution and reads from it when it needs context. This is not a new idea — cognitive architectures like SOAR and ACT-R modeled human memory as distinct subsystems decades ago. What is new is applying these patterns to LLM-based agents at scale.

As Krishnan (2025) notes in AI Agents: Evolution, Architecture, and Real-World Applications, modern agent architectures integrate large language models with dedicated modules for perception, planning, and tool use. Memory is the connective tissue between those modules.

Conceptual Foundation: Types of Agent Memory

Human cognitive science distinguishes between several types of memory. Two are particularly useful for agent design: episodic memory and semantic memory.

Episodic memory stores specific events and experiences. For an agent, this means: "At 2:30 PM, I called the weather API and got a timeout error." Episodic memories are timestamped, ordered, and tied to a specific context.

Semantic memory stores general knowledge and facts distilled from experience. For an agent, this means: "The weather API tends to time out during peak hours; use the cached endpoint instead." Semantic memories are abstracted, deduplicated, and context-independent.

There is a third type worth mentioning: procedural memory, which stores how to do things. In agent systems, this maps to learned tool-use patterns, prompt templates that worked well, or refined chain-of-thought strategies. We will not cover procedural memory in depth here, but know that it exists in the design space.

Property	Episodic Memory	Semantic Memory
Content	Specific events, observations	Distilled facts, generalizations
Structure	Timestamped, sequential	Key-value, graph-linked
Retention	Can be pruned over time	Long-lived, updated in place
Retrieval	By time range, similarity to current context	By concept, relationship, keyword
Example	"User asked about refund policy on March 3"	"Refund policy requires order ID and proof of purchase"

A well-designed memory layer supports both types. Episodic memory gives your agent a detailed history to reason over. Semantic memory gives it compressed, reliable knowledge to act on quickly.

Architecture Overview

Here is the core architecture for a universal memory layer. Study the flow from agent action through to retrieval.

graph TD
    A["Agent Action / Observation"] --> B["Episodic Buffer"]
    B --> C["Memory Processor"]
    C --> D["Long-Term Memory Store"]
    D --> E["Vector Index"]
    D --> F["Keyword Index"]
    D --> G["Graph Index"]
    H["Agent Context Window"] -->|"retrieval query"| I["Hybrid Retrieval Engine"]
    E --> I
    F --> I
    G --> I
    I -->|"ranked memories"| H
    C -->|"semantic extraction"| J["Semantic Memory Store"]
    J --> G
    J --> E

Let us walk through each component.

1. Agent Action Produces an Observation

Every time your agent does something — calls a tool, receives user input, generates a response — it produces an observation. This is the raw material for memory. The observation includes the content itself, a timestamp, the agent's identifier, and any metadata (tool name, user ID, task ID).

2. Episodic Buffer Stages the Memory

Before writing to long-term storage, observations land in an episodic buffer. This is a short-lived queue that allows batching, deduplication, and importance scoring. Not every observation deserves to be a long-term memory. The buffer gives you a place to apply filters.

3. Memory Processor Writes to Long-Term Storage

The processor takes buffered observations, generates embeddings (for vector search), extracts entities and relationships (for graph search), and indexes keywords (for BM25/keyword search). It also runs a semantic extraction step: distilling episodic memories into semantic memories when patterns emerge.

4. Hybrid Retrieval Fetches Relevant Memories

When the agent needs context, it sends a retrieval query to the hybrid retrieval engine. This engine queries all three indexes — vector, keyword, and graph — then merges and re-ranks the results. The top-ranked memories are injected into the agent's context window as part of the system prompt or as retrieved context.

Designing an Interoperable Memory Schema

If you are building a multi-agent system, your memory schema needs to work across agents that may have different roles, different tools, and different LLM backends. This means the schema must be self-describing and loosely coupled.

Here is a practical schema in JSON that covers both episodic and semantic memories:

from dataclasses import dataclass, field
from typing import Optional
from datetime import datetime
import uuid
import json

@dataclass
class MemoryRecord:
    """Universal memory record usable across any agent in the system."""
    content: str                          # The actual memory content
    memory_type: str                      # "episodic" or "semantic"
    agent_id: str                         # Which agent created this memory
    timestamp: str = field(
        default_factory=lambda: datetime.utcnow().isoformat()
    )
    memory_id: str = field(
        default_factory=lambda: str(uuid.uuid4())
    )
    embedding: Optional[list[float]] = None  # Vector embedding, set during processing
    entities: list[str] = field(default_factory=list)  # Extracted entities for graph index
    relationships: list[dict] = field(default_factory=list)  # Entity-to-entity links
    metadata: dict = field(default_factory=dict)  # Flexible metadata (tool, task_id, etc.)
    trust_score: float = 1.0              # How much other agents should trust this memory
    access_count: int = 0                 # How often this memory has been retrieved
    ttl: Optional[int] = None             # Time-to-live in seconds; None = permanent

    def to_dict(self) -> dict:
        return {k: v for k, v in self.__dict__.items() if v is not None}

# Example: creating an episodic memory
episode = MemoryRecord(
    content="Called /api/weather for zip 94103. Received 504 Gateway Timeout after 30s.",
    memory_type="episodic",
    agent_id="weather-agent-01",
    entities=["weather_api", "zip_94103"],
    relationships=[{"from": "weather_api", "relation": "timed_out_for", "to": "zip_94103"}],
    metadata={"tool": "http_get", "status_code": 504, "task_id": "task-abc-123"}
)

print(json.dumps(episode.to_dict(), indent=2))

Expected output:

{
  "content": "Called /api/weather for zip 94103. Received 504 Gateway Timeout after 30s.",
  "memory_type": "episodic",
  "agent_id": "weather-agent-01",
  "timestamp": "2026-03-05T14:22:01.123456",
  "memory_id": "a1b2c3d4-...",
  "entities": ["weather_api", "zip_94103"],
  "relationships": [{"from": "weather_api", "relation": "timed_out_for", "to": "zip_94103"}],
  "metadata": {"tool": "http_get", "status_code": 504, "task_id": "task-abc-123"},
  "trust_score": 1.0,
  "access_count": 0
}

The trust_score field is critical in multi-agent systems. When Agent B reads a memory written by Agent A, it needs to assess reliability. Trust scores can be updated based on whether memories led to successful outcomes. The access_count field enables least-recently-used pruning for storage management.

Schema Versioning Matters

Once multiple agents share a memory store, changing the schema becomes a coordination problem. Include a schema_version field in your metadata from day one. Migrations in multi-agent systems are significantly harder than in single-service architectures because you cannot take the memory layer offline for a migration while agents are running.

Hybrid Search: Vector + Keyword + Graph

No single search method handles all memory retrieval scenarios well. Here is why you need all three.

Vector search (using embeddings) excels at semantic similarity. "The API returned an error" will match "HTTP request failed" even though they share no keywords. But vector search struggles with precise lookups: searching for "task-abc-123" by embedding similarity is unreliable.

Keyword search (BM25 or similar) excels at exact and partial matches. Searching for a specific task ID, agent name, or error code is fast and deterministic. But keyword search misses semantic relationships entirely.

Graph search excels at relationship traversal. "What do we know about all entities connected to the weather API?" is a graph query. Neither vector nor keyword search can answer this efficiently.

Here is a practical implementation of hybrid retrieval using Python:

from dataclasses import dataclass
import numpy as np
from typing import Optional

@dataclass
class SearchResult:
    memory_id: str
    content: str
    score: float
    source: str  # "vector", "keyword", or "graph"

def cosine_similarity(a: list[float], b: list[float]) -> float:
    """Compute cosine similarity between two vectors."""
    a_arr, b_arr = np.array(a), np.array(b)
    return float(np.dot(a_arr, b_arr) / (np.linalg.norm(a_arr) * np.linalg.norm(b_arr) + 1e-10))

def vector_search(
    query_embedding: list[float],
    memory_store: list[dict],
    top_k: int = 5
) -> list[SearchResult]:
    """Search memories by embedding similarity."""
    scored = []
    for mem in memory_store:
        if mem.get("embedding"):
            sim = cosine_similarity(query_embedding, mem["embedding"])
            scored.append(SearchResult(
                memory_id=mem["memory_id"],
                content=mem["content"],
                score=sim,
                source="vector"
            ))
    scored.sort(key=lambda r: r.score, reverse=True)
    return scored[:top_k]

def keyword_search(
    query_terms: list[str],
    memory_store: list[dict],
    top_k: int = 5
) -> list[SearchResult]:
    """Simple BM25-style keyword matching."""
    scored = []
    for mem in memory_store:
        content_lower = mem["content"].lower()
        # Count how many query terms appear in the content
        hits = sum(1 for term in query_terms if term.lower() in content_lower)
        if hits > 0:
            # Normalize by number of query terms
            score = hits / len(query_terms)
            scored.append(SearchResult(
                memory_id=mem["memory_id"],
                content=mem["content"],
                score=score,
                source="keyword"
            ))
    scored.sort(key=lambda r: r.score, reverse=True)
    return scored[:top_k]

def graph_search(
    entity: str,
    memory_store: list[dict],
    max_hops: int = 2
) -> list[SearchResult]:
    """Find memories connected to a given entity through relationships."""
    results = []
    visited_entities = {entity}
    frontier = [entity]

    for hop in range(max_hops):
        next_frontier = []
        for mem in memory_store:
            for rel in mem.get("relationships", []):
                if rel["from"] in frontier or rel["to"] in frontier:
                    results.append(SearchResult(
                        memory_id=mem["memory_id"],
                        content=mem["content"],
                        score=1.0 / (hop + 1),  # Closer hops score higher
                        source="graph"
                    ))
                    # Add connected entities to next hop
                    for key in ["from", "to"]:
                        if rel[key] not in visited_entities:
                            next_frontier.append(rel[key])
                            visited_entities.add(rel[key])
        frontier = next_frontier
    return results

def hybrid_search(
    query_embedding: list[float],
    query_terms: list[str],
    entity: Optional[str],
    memory_store: list[dict],
    weights: dict = None,
    top_k: int = 5
) -> list[SearchResult]:
    """
    Merge results from all three search methods using weighted reciprocal rank fusion.
    """
    if weights is None:
        weights = {"vector": 0.5, "keyword": 0.3, "graph": 0.2}

    all_results: dict[str, float] = {}  # memory_id -> fused score
    result_content: dict[str, str] = {}

    for search_fn, args, source_key in [
        (vector_search, (query_embedding, memory_store), "vector"),
        (keyword_search, (query_terms, memory_store), "keyword"),
    ]:
        results = search_fn(*args)
        for rank, result in enumerate(results):
            # Reciprocal rank fusion: 1/(rank+1) * weight
            rrf_score = (1.0 / (rank + 1)) * weights[source_key]
            all_results[result.memory_id] = all_results.get(result.memory_id, 0) + rrf_score
            result_content[result.memory_id] = result.content

    if entity:
        graph_results = graph_search(entity, memory_store)
        for rank, result in enumerate(graph_results):
            rrf_score = (1.0 / (rank + 1)) * weights["graph"]
            all_results[result.memory_id] = all_results.get(result.memory_id, 0) + rrf_score
            result_content[result.memory_id] = result.content

    # Sort by fused score
    sorted_ids = sorted(all_results.keys(), key=lambda mid: all_results[mid], reverse=True)
    return [
        SearchResult(
            memory_id=mid,
            content=result_content[mid],
            score=all_results[mid],
            source="hybrid"
        )
        for mid in sorted_ids[:top_k]
    ]

The hybrid_search function uses reciprocal rank fusion (RRF) to combine results. RRF is simple and effective: it assigns each result a score of 1/(rank+1), weighted by the search method's importance. Memories that appear in multiple search results get boosted naturally. This approach outperforms naive score averaging because scores from different search methods are not on the same scale.

Tuning Hybrid Search Weights

The default weights (0.5 vector, 0.3 keyword, 0.2 graph) are a reasonable starting point. In practice, tune these based on your retrieval evaluation set. If your agent frequently needs exact ID lookups, increase the keyword weight. If your domain is heavily relational (e.g., knowledge graphs, org charts), increase the graph weight.

Semantic Extraction: Turning Episodes into Knowledge

Episodic memories accumulate fast. If your agent runs 1,000 tasks per day, you will have 1,000+ episodic records within hours. Retrieval degrades as the store grows. Semantic extraction addresses this by periodically distilling episodic memories into compact semantic memories.

Here is a simplified extraction pipeline:

def extract_semantic_memories(
    episodic_memories: list[dict],
    similarity_threshold: float = 0.85
) -> list[dict]:
    """
    Group similar episodic memories and distill them into semantic memories.
    In production, you would use an LLM to generate the summary.
    """
    clusters: list[list[dict]] = []

    for mem in episodic_memories:
        placed = False
        for cluster in clusters:
            # Compare against the first memory in each cluster (simplified)
            sim = cosine_similarity(mem["embedding"], cluster[0]["embedding"])
            if sim >= similarity_threshold:
                cluster.append(mem)
                placed = True
                break
        if not placed:
            clusters.append([mem])

    semantic_memories = []
    for cluster in clusters:
        if len(cluster) >= 3:  # Only distill if we have enough evidence
            # In production, pass cluster contents to an LLM for summarization
            combined_content = " | ".join(m["content"] for m in cluster)
            semantic_memories.append({
                "content": f"[Distilled from {len(cluster)} episodes] {combined_content[:200]}...",
                "memory_type": "semantic",
                "agent_id": "memory-processor",
                "source_count": len(cluster),
                "source_ids": [m["memory_id"] for m in cluster],
                "trust_score": min(m.get("trust_score", 1.0) for m in cluster),
            })

    return semantic_memories

In a production system, you would replace the simple concatenation with an LLM call that generates a proper summary. The key design choice is the similarity_threshold: too low and you merge unrelated memories; too high and nothing gets distilled.

Do Not Delete Episodic Memories After Extraction

It is tempting to delete episodic memories once they have been distilled into semantic memories. Do not do this in your first iteration. Semantic extraction is lossy — the summary may miss critical details. Keep episodic memories with a TTL (e.g., 30 days) so you can fall back to them during retrieval. Archive rather than delete.

Real-World Considerations

Storage Costs and Pruning

Embeddings are not small. A 1536-dimensional float32 embedding consumes about 6 KB. At 10,000 memories, that is 60 MB of embeddings alone. At 10 million, it is 60 GB. Plan your pruning strategy early: TTL-based expiry for episodic memories, access-count-based eviction for infrequently-used semantic memories, and compression for archived records.

Latency Budgets

Your agent is waiting for memories before it can generate a response. If hybrid retrieval takes 500ms, that 500ms is added to every agent turn. For real-time applications, consider a two-tier cache: a fast in-memory cache of recently accessed memories (hits in under 5ms) backed by the full indexed store (hits in 50-200ms).

Multi-Agent Trust and Conflict Resolution

When Agent A writes "the refund policy requires a receipt" and Agent B writes "the refund policy does not require a receipt," your memory layer has a conflict. Trust scores help here — you can weight memories by the trust score of the authoring agent — but they do not eliminate the problem. Consider adding a conflict detection step during retrieval that flags contradictory memories for the consuming agent to resolve.

When Not to Use a Memory Layer

Not every agent needs persistent memory. If your agent handles isolated, stateless tasks (e.g., a code formatter, a one-shot classifier), the overhead of a memory layer adds complexity without benefit. The memory layer pays off when agents run over extended periods, collaborate with other agents, or need to improve based on past experience.

Seeing This in Practice

The patterns described above — interoperable memory schemas, trust scoring across agents, and hybrid retrieval from a shared memory store — are implemented in SuperLocalMemory, an open-source memory layer that runs entirely on your local machine with no cloud dependency.

Its multi-agent shared memory architecture assigns trust scores to memories based on the authoring agent's track record and uses a schema compatible with 16+ tools including Claude and Cursor. You can inspect how the memory write/read flow works by cloning the repository:

git clone https://github.com/varun369/SuperLocalMemoryV2.git
cd SuperLocalMemoryV2
# Examine the memory schema and retrieval logic
cat src/memory/schema.py
cat src/memory/retrieval.py

This gives you a concrete reference implementation to compare against the architectural patterns discussed here. Reviewing working code is often more instructive than reading about patterns in the abstract.

Forem: varun pratap Bhardwaj

I Built an OS for AI Agents — Here's What I Learned

The problem nobody warned me about

The core insight: agents need what programs got

What shipped in v2.2.0

The 7-perspective audit story

What doesn't work well yet

The data loss story

The technical choices, briefly

What I'd do differently

Try it

The Qualixar AI Agent Reliability Platform

Run Multi-Agent Teams from Claude Code with Qualixar OS (25 MCP Tools)

Run Multi-Agent Teams from Claude Code with Qualixar OS (25 MCP Tools)

Installation

MCP Server Configuration

The 25 MCP Tools

Task Execution

Agents and Forge AI

Quality and Memory

Chat and Data

Blueprints and Prompts

System

Tutorial: Code Review Team via Forge AI

Step 1: Submit the task

Step 2: Inspect the Forge design

Step 3: Monitor execution

Step 4: Check quality scores

Step 5: View in the dashboard

Advanced: Topology Selection and Cost Constraints

Choosing a topology

Budget constraints

Dry run

A2A: Agent-to-Agent Protocol

Links

The Qualixar AI Agent Reliability Platform

I Tracked Why AI Agent Projects Fail. 80% of the Time, It's Not the Agents.

The numbers nobody talks about

The five infrastructure problems every agent team solves from scratch

1. The routing problem

2. The quality problem

3. The memory problem

4. The cost problem

5. The observability problem

Why this isn't a framework problem

The topology dimension most teams miss

A checklist before you build

What I'm building about it

The Qualixar AI Agent Reliability Platform

Your Multi-Agent System Probably Uses 1 Pattern. Here Are 12.

Simple Topologies

1. Sequential

2. Parallel

Structured Topologies

3. Hierarchical

4. DAG (Directed Acyclic Graph)

5. Star

6. Grid

Collaborative Topologies

7. Debate

8. Mesh

9. Circular (Round-Robin)

10. Mixture-of-Agents

Specialized Topologies

11. Forest

12. Maker (Build-Test-Ship)

Choosing the Right Topology

One More Thing

DEMO

PORTAL WALKTHROUGH

I Tracked Why AI Agent Projects Fail. 80% of the Time, It's Not the Agents.

The numbers nobody talks about

The five infrastructure problems every agent team solves from scratch

1. The routing problem

2. The quality problem

3. The memory problem

4. The cost problem

5. The observability problem

Why this isn't a framework problem

The topology dimension most teams miss