Parker Jones Dev Blog - context-harness

A Hammer Still Looking for Its Nail: Context Harness and the Team-Context Problem

2026-06-29T00:00:00+00:00

Part 1</a> was the engine: a local-first RAG index in Rust — SQLite, hybrid search, Lua connectors, served to any tool over MCP. This post is the harder question one layer up, the one the engine only makes sense as an answer to: context that stays current and shareable across a team — and whether Context Harness</a> is really the shape of that answer, or a hammer I enjoyed building and then went looking for a nail to justify. 

I want to be honest about the register here, because it's different from Part 1. That post was a retrospective — a thing I built, surveyed, and understood. This one isn't finished. Context Harness is a work in progress, and I'm still genuinely working out whether its core bet is right. So this is me reasoning in public, dogfooding a tool and watching whether it earns its place — not selling you a conclusion I don't have. Pretending otherwise would be its own kind of slop, which is funny, because slop is the thing the tool exists to fight.

The itch</h2>
Context Harness came from confabulation. AI tools are great until they start confidently inventing details about my code — a function signature that doesn't exist, a config key I never wrote, a system summarized the way it isn't. The fix is grounding: give the model the real material and it stops guessing. Cursor</a> does this with semantic search over a repo. I wanted that, but portable, multi-repo, and pointable at any pile of my own work — and the index it builds is a database (a SQLite file, hybrid keyword-plus-vector search, served to any tool over MCP). That's the engine I described in Part 1</a>.
I'm already in the format camp</h2>
Before I defend the engine, I should admit which side I've actually lived on. The loudest current answer to "how do you give AI context" isn't an engine at all — it's a format: markdown with frontmatter, in a directory, that agents read directly. Google's Open Knowledge Format</a>, Karpathy's LLM-wiki</a>, the `AGENTS.md</code> convention, every Obsidian vault. No SDK, no runtime, no index — the format is the contribution, and a long-context model just reads the files.`
`I'm not skeptical of this from the outside. I've kept markdown knowledge vaults for years — personal and professional — since before "LLM wiki" was a phrase. For one person, or a couple of people who trust each other's notes, it is genuinely the right tool. Lightweight, portable, human-readable, version-controlled. If that's your scale, you probably don't need anything I'm building.`
Where the format quietly breaks</h2> It breaks at team scale, and I've watched it break. Past about three people, a shared markdown corpus develops the same disease every wiki has ever had: it goes stale, nobody owns curating it, and it grows into an overwhelming pile of text that no one trusts is current. The format assumes someone keeps the files good. At small scale that someone exists. On a large engineering team riddled with silos, they don't — and "just read the folder" turns into "read a thousand documents, half of them six months out of date, and hope." This isn't a niche complaint. Portable, shareable, current team context is, as far as I can tell, an unsolved problem — even well-resourced internal tooling at large companies hasn't really cracked it. That part I'm confident about. It's the part I'm less sure about that this whole post is circling.The bet I'm dogfooding</h2> Context Harness's bet is that the thing markdown can't be — at team scale — is exactly what a context engine can: a shared store that stays current (it re-syncs from the sources instead of waiting for a human to update prose), is shareable (the index is an artifact a team can pull, not a vault each person curates alone), and possesses skills rather than being inert text — the Lua connectors, tools, and agents that let it ingest weird sources and act on what it finds. A worthy context tool, the way I think about it, is a current, shareable thing that does things — not an overwhelming corpus that rots. The whole argument in one picture: the format camp is right up to team scale, where it rots — and the bet is that a current, shareable, skill-bearing index is the thing markdown structurally can't be.</figcaption> </figure> Two honest clarifications, because they matter and they cut against my own earlier framing: "Local-first" is mostly a cover story. Under the hood the design is configuration-driven, with multiple backends — local is one configuration, not a religion — and yes, there's a paid tier in the back of my mind. That flexibility is precisely what could make it team-shareable; a purist local-only tool couldn't be.</li> Search is a component, not the point. A serious context tool needs good retrieval, sure. But "search the blog" and "keep a team's context fresh and shareable" only overlap at the word search. The first is a commodity; the second is the actual problem. I spent a whole post in another series</a> untangling the same search-versus-state conflation, and I don't want to repeat it here.</li> </ul> The browser-RAG tangent (still half-baked)</h2> There's a tempting offshoot I haven't resolved: ctx export</code> already dumps the index to JSON, and you could pair that with on-device embeddings (Transformers.js</a> with the same small all-MiniLM-L6-v2</code> model the engine can embed with locally) and a vector index (sqlite-vec</code></a> runs in WASM) to do retrieval entirely in a browser tab. For a forty-post blog it's a 25MB model aimed at a mosquito. For the multi-repo workspace the engine was built for, maybe not. I file it under "experiments I want to run," not "roadmap." What I'm actually doing about it</h2> Dogfooding, mostly — which is the only honest way to find out if the bet holds. I run Context Harness against my own vaults and my own multi-repo work, and I watch for the moment it either earns its keep or doesn't: does a freshly-synced, shareable, skill-bearing index actually beat "just keep good markdown," once the corpus is too big and too shared for any one person to keep good? I don't have that answer yet. Some days the format camp looks obviously right and the engine looks like a hammer I built because hammers are fun. Other days I hit exactly the staleness-at-scale wall the engine is meant for, and it feels like the only thing that could work. The meta-loop is the honest ending, and I'll leave it unresolved on purpose: I built a tool to fight AI slop by grounding models in real context, I'm using a model to reason about whether that tool is even the right shape, and the answer is genuinely I'm still finding out. Naming that uncertainty — instead of papering over it with a confident conclusion — is the same discipline the tool is supposed to enforce on the models. So that's where Context Harness is: a hammer still looking for its nail, being swung in public until I know whether the nail is real. — Parker Jones

Context Harness: a Local-First RAG Engine in Rust with Lua Extensions and an MCP Server 2026-06-26T00:00:00+00:00 AI tools are only useful when they can see your context — your docs, your code, your notes, the Hacker News thread you read last week. The usual answer is a cloud RAG service: ship your data to someone's vector database, pay per query, hope it's still up. I wanted the opposite — a single binary that ingests my stuff, indexes it locally, and hands it to any AI tool over a standard protocol, with no cloud dependency. So I built Context Harness</a> (ctx</code>). $ ctx --help Context Harness provides a connector-driven pipeline for ingesting documents from multiple sources (filesystem, Git repositories, S3 buckets), chunking and embedding them, and exposing hybrid search (keyword + semantic) via a CLI and MCP-compatible HTTP server. </code></pre> It's a RAG engine that lives on your laptop. Here's the design. The pipeline</h2> The flow is the standard RAG shape, but every stage is local and configurable through one ctx.toml</code>: connectors → sync → chunk → embed → SQLite → hybrid search → CLI / MCP </code></pre> Connectors define where documents come from — filesystem globs, Git repos, S3 buckets, or custom Lua scripts (more on those below). ctx sync</code> pulls from a connector and runs the rest of the pipeline. Chunking and embedding are configured, not hard-coded: [chunking] max_tokens = 700 overlap_tokens = 80 [embedding] provider = "openai" model = "text-embedding-3-small" dims = 1536 </code></pre> The provider</code> is pluggable — that line can point at OpenAI's text-embedding-3-small</code>, or at a fully local model. My test setup runs fastembed</code> with a quantized all-MiniLM-L6-v2</code> ONNX model, so embeddings happen on-device with no API call at all. That choice is the whole "local-first" thesis in one config key: trade a little retrieval quality for zero cloud dependency and zero per-query cost. Storage is SQLite. No vector-database service to stand up, no Docker, no daemon. The index is a file you can copy, back up, or delete. For a single-user knowledge base, a managed vector DB is wildly over-provisioned; SQLite is exactly right. Hybrid search</h2> Pure semantic search misses exact terms; pure keyword search misses paraphrase. ctx</code> does both and blends them: [retrieval] final_limit = 12 hybrid_alpha = 0.6 # weight toward semantic vs keyword candidate_k_keyword = 80 # pull 80 keyword candidates candidate_k_vector = 80 # and 80 vector candidates group_by = "document" # then dedup/group by document doc_agg = "max" max_chunks_per_doc = 3 </code></pre> It gathers candidates from both a keyword index and a vector index, blends the scores with hybrid_alpha</code>, groups by document so one long file can't flood the results, and returns the top 12. Tuning hybrid_alpha</code> toward 0 or 1 lets you dial between "find the exact phrase" and "find the related idea." The part that makes it an engine: the MCP server</h2> A search CLI is handy. A search CLI that any AI tool can call as a tool is a force multiplier: $ ctx serve mcp # Exposes search/get over a JSON API for Cursor, Claude, and other # MCP-compatible AI tools. </code></pre> MCP</a> is the protocol AI tools use to call external tools. By speaking it, ctx</code> turns your local knowledge base into a tool the model can reach for mid-conversation: "search my notes for the retry-policy decision," and the model queries your SQLite index and gets grounded results — without your notes ever leaving the machine. That's the feature I use every day. Extensibility: connectors, tools, and agents in Lua</h2> Built-in connectors cover the common cases, but the interesting data is always somewhere weird. So ctx</code> embeds Lua: you can script connectors (new data sources), tools (new capabilities), and agents (personas with a system prompt and a scoped toolset). Each has init</code>/test</code> scaffolding: $ ctx connector init # scaffold a new Lua connector from a template $ ctx connector test # run it without writing to the DB $ ctx agent init/test/list </code></pre> The agent system is the one I'm proudest of. An agent is a Lua script that, at resolve time, assembles its own context by querying the knowledge base, then hands the model a system prompt plus pre-loaded research and a scoped set of tools. Here's a real one — hn-writer</code>, which writes Hacker News launch posts: agent = { name = "hn-writer", description = "Write Hacker News posts by studying top HN content and your product docs", tools = { "search", "get" }, -- scoped: this agent can only search and fetch arguments = { { name = "style", description = "show_hn, launch, ask_hn, or discussion" }, { name = "angle", description = "e.g. 'local-first', 'developer tooling'" }, { name = "tone", description = "technical, conversational, or minimal" }, }, } function agent.resolve(args, config, context) -- pre-load HN trends from the knowledge base for _, q in ipairs({ "Show HN", "Rust CLI tool", "local first", "AI context" }) do local results = context.search(q, { mode = "keyword", limit = 5 }) -- ...fold the top results into the prompt as research... end -- ...also search the project's own docs, then return: return { system = system_prompt, tools = { "search", "get" }, messages = preloaded } end </code></pre> What I love about this pattern: the agent does its own retrieval before the model gets involved, so the model starts with both "what performs well on HN right now" (from a connector that ingests HN) and "what this product actually does" (from a filesystem connector over the docs) already in context. And there's a pleasant recursion to it — I have an agent whose job is to write the Show HN post for the tool the agent runs on. Its prompt even encodes the house style: "What HN hates: marketing speak, buzzwords, superlatives… technical substance over marketing language." Which, not coincidentally, is the ethos of this whole blog. Sharing extensions: registries</h2> Lua scripts are shareable, so ctx</code> supports registries — git repos of community connectors, tools, and agents that sync in automatically: [registries.community] url = "https://github.com/parallax-labs/ctx-registry.git" auto_update = true readonly = true </code></pre> A registry is just a versioned directory of .lua</code> files; pointing at one makes its connectors and agents available locally. It's the same "distribute capability declaratively" idea I use for agent skills</a>, applied to data connectors. Static-site search, for free</h2> One more trick. ctx export</code> dumps the whole index to JSON for client-side search: $ ctx export # Exports documents and chunks to JSON for use with ctx-search.js — # client-side search on a static site. </code></pre> Which means the same engine that grounds my AI tools could also power search on this blog — index the posts, export the JSON, search it in the browser with no backend. (My terminal theme already runs a database in the browser</a>, so this is a natural next step.) Honest trade-offs</h2> Context Harness is young, and local-first is a set of trade-offs, not a free lunch: Local embeddings are private and free but lower-quality than the big cloud models. provider</code> lets you choose per use case, but you don't get both at once.</li> SQLite scales to a personal knowledge base, not a team's corpus. That's the design target, not a bug — but know the ceiling.</li> Lua is power and rope. Scriptable connectors mean I can ingest anything; they also mean a bad script can do bad things. connector test</code> (which never writes to the DB) exists for exactly that reason.</li> </ul> But the core bet has paid off: a single Rust binary, a SQLite file, optional fully-local embeddings, and a standard protocol is enough to give every AI tool I use grounded access to my own context — without renting a vector database to do it. Context Harness is open source (AGPL-3.0) at parallax-labs/context-harness</code></a>; docs and prebuilt binaries for macOS and Linux are at parallax-labs.github.io/context-harness</a>. — Parker Jones, parkerjones.dev</a>

Parker Jones Dev Blog - context-harness

A Hammer Still Looking for Its Nail: Context Harness and the Team-Context Problem

Context Harness: a Local-First RAG Engine in Rust with Lua Extensions and an MCP Server

The pipeline</h2> The flow is the standard RAG shape, but every stage is local and configurable through one ctx.toml</code>:</p>