Articles

Long-form writing on building Neural Junkie — hardware limits, model layering, LoRA composition, conversation memory, personal learning, multi-agent collaboration, and how we test it. Originally drafted for LinkedIn; published here for the open-source community.

26 articles
v1.2.0-beta.20: Install, Update, and Ship Artifacts

One-click Ollama on Windows, macOS, and Linux with real password/UAC dialogs, signed Tauri v2 auto-updates, Neural Canvas + Maps, semantic turn routing, and Share Agent packaging — everything since beta.6, culminating in install-and-go local AI.

v1.2.0-beta.6: A Memory of Its Own Code

Native knowledge graph, Model Arena, MQTT/Kafka stream subscriptions, PrismML Bonsai 27B, Room Chat, Homebrew installs, and the polish beta users asked for — pack toolbar chips and workspace image previews that finally just work.

v1.2.0-beta.5: The Release Where the Loops Close

Runbooks you can replay, routing you can audit, collab hardened by live scenario gates, ReAct tools on Gemma, multi-repo workspace scope, LoRA v2 specialists, and the release engineering that keeps betas honest — everything shipping in Neural Junkie beta.5 this week.

One Decision Per Turn: Meaning Over Phrases

Neural Junkie replaces distributed phrase matching with one server-authoritative semantic decision per turn — local structured classification for meaning, deterministic policy for writes, recipients, retrieval, and Ask/Plan safety.

The Composition Model: Agents, Tools, and Runbooks You Can Actually Take With You

Neural Junkie treats agents, tools, and runbooks as portable, composable units — Share Agent bundles knowledge you can hydrate anywhere, the MCP Tool Wizard grants a home-grown tool to one agent by name, and runbook definitions export/import with a provenance trail back to the events that produced each run.

What Your Machine Actually Needs to Run a Local AI Engineering Team

Neural Junkie ships as a ~15 MB desktop app — but your first local model pull can be 14 GB+. Here is how RAM tiers map to model tags, why multi-agent ≠ multi-model, and what we do not hide in open beta.

The Hub Is the Product: Why Neural Junkie Isn't a Chatbot

Most AI tools are chat UIs or IDE plugins. Neural Junkie is a local Go hub — channels, agents, collaboration phases, file approvals, and model routing in one orchestrator your desktop, browser, Slack, and CLI all talk to. Here's why we built it that way.

How Neural Junkie Builds, Uses, and Shares Agent Context

Every turn flows through a six-stage Conversation Context Stack — mode, intent, memory, grounding, persona, budget — then shares only what's needed via channels, delegation, collabs, learnings, and retrieve-on-demand memory. Scoped context, not a hive mind.

We Don't Use One Model. We Layer Them.

One 14B model can't be your security reviewer, biology expert, session summarizer, and cheap typo-fixer. Neural Junkie layers models at four levels — context, weights, routing, and orchestration — so local multi-agent work stays fast, grounded, and under your control.

Modular AI, Local Hardware: How Neural Junkie Routes Instead of Guessing

Stop running one model for everything. Neural Junkie composes specialists at the orchestration layer — a small classifier picks domain and cost tier, packs declare chat/tool/LoRA stacks, and every reply shows which model actually ran.

Decide Before You Generate: Neural Junkie's Inference Layer

Everyone optimizes inference speed. Almost nobody optimizes inference *avoidance*. Neural Junkie's inference layer decides whether to call a model, which brain to use, and which provider runs the job — then shows you the answer on the message itself.

We Didn't Build One Agent Loop. We Built a Stack.

My agent could run `make start-all` eight times and never touch the Makefile. That's not a model problem — it's a missing closed loop. Here's the stack of loops we built in Neural Junkie, and why each one exists.

Gemma Can't Call Tools. We Taught It Anyway.

Strong local models like Gemma 3 12B reason well but lack native function calling. Neural Junkie's ReAct wrapper runs MCP tools on the same model — with Qwen swap as a safety net when parsing fails.

Execution Is Not Repair: Building the NJ Fix Loop

My agent could run `make start-all` eight times and never touch the Makefile. Execution worked; repair didn't. Here's the platform policy we added so boot-fix sessions read, edit, verify, and always report an outcome.

Green Tests Aren't Enough: Fix Loops and Growth Loops for Agent Platforms

My collab suite was red for weeks. Click-testing a 3-hour multi-agent sweep doesn't scale. So I wired three release loops: gate → fix → grow. Here's what each one does, and why you need both repair *and* test growth.

Build the IDE You Actually Own

IDE v4 adds Monaco LSP, remote SSH via nj-remote, dev containers, and tree-sitter symbols — local-first and open source, for when the IDE you loved has a new owner.

Your Agents Forget. Neural Junkie Remembers — Without Sending the Whole Transcript.

Neural Junkie agents used to forget anything outside the last few messages. Conversation memory indexes your full channel history and collab artifacts locally, then pulls back only what's relevant to your latest question — no cloud vector DB, no stuffing the whole transcript into context.

Nothing Gets Remembered Until You Say So: Personal Learning in Neural Junkie

Your agents shouldn't silently learn from every typo and half-formed thought. Neural Junkie personal learning stores only what you confirm — scoped per expert, globally, or per collaboration — retrieved by local embeddings and optionally exported into LoRA training rows.

One Base Model. Many Specialists. LoRA Inside Neural Junkie.

Running five local specialists shouldn’t mean five full 14B downloads. Neural Junkie composes Ollama tags from one base + small LoRA adapters — import from Hugging Face, install pack presets, or train from your own chat and collab history.

LoRA v2: When Your Repo Expert Starts Compounding

LoRA v1 let you train a specialist from chat history and assign an Ollama tag. It worked — but it felt like a sidecar. LoRA v2 closes the loop: incremental refresh, dual-tag profiles, unified routing, MLX on Apple Silicon, and team sharing via MCP + Hugging Face.

Why We Split Inference and LoRA Into Two Tiers

We wanted one Qwen base + tiny LoRA adapters for every specialist. Ollama said no — safetensors LoRA only works on Llama/Mistral/Gemma. Here's how Neural Junkie split inference (Qwen) from train/compose (Llama) without breaking the hub.

Two Layers, One Specialist: MCP Exports and LoRA in Neural Junkie

Repo experts accumulate real value — indexed code, session Q&A, architecture notes. We export that as portable MCP packages *and* optionally fine-tune LoRA adapters from the same sessions. Same ambition, different layer: context you can share vs weights that lean local inference toward your domain.

Multi-Agent Collaboration Is Easy to Demo. Hard to Ship.

`/collaborate` looks like one command. Under the hood it’s phases, task dependencies, workspace gates, and file approvals — while real models improvise. Here’s why that’s hard, and the three-layer test harness I’m building so it doesn’t stay a demo.

When Does Multi-Agent Actually Help?

`/collaborate` looks impressive in demos. But when does two agents actually beat one specialist on the same deliverable? I built a parity scenario — same repo, same findings.md task, solo DM vs. structured collab — so we can measure it instead of debating it.

You Can’t Unit Test a Conversation. So I Built This Instead.

Prompts and models change weekly. Click-testing a multi-agent hub doesn’t scale. Here’s the three-layer harness I built for Neural Junkie — deterministic Go tests for the orchestrator, CI smoke for the pipeline, and JSON scenarios with real Ollama agents for conversation quality.

Streams In. Agents Out: MQTT and Kafka Triggers for Local Runbooks

MQTT and Kafka don't need a chatbot sitting on the topic. Neural Junkie adds long-lived stream subscriptions that match messages and fire a runbook, post into a hub channel, or call a webhook — Settings UI included.