DEV Community: Swarnnim Agnihotri

DiffScribe: The Commit Message Writes Itself (Locally)

Swarnnim Agnihotri — Mon, 26 Oct 2026 20:40:28 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

The most lied-to text box in software

Every developer knows the moment. The work is done, the tests pass, and
then you face the emptiest, most judgmental input field in all of
software: the commit message box. So you type what we all type:

fix stuff
updates
final version (2)

Git keeps perfect records of what changed. The why and the what it
means live in commit messages and changelogs — the two texts written
last, fastest, and worst. git log archaeology is a running joke
precisely because the record we leave behind is so much worse than the
work it describes.

The fashionable fix is to paste your diff into a cloud AI and let it
write the message. That works, and it also means shipping your
unreleased code — every secret you forgot to gitignore, every internal
hostname — to someone else's server, per commit, forever.

I wanted the drafting help without the disclosure. So for this week's
challenge I built DiffScribe: a small command-line tool that reads a
git diff and drafts a conventional-commit message and a changelog entry,
running entirely on my own machine. The AI at its core is an open-weight
model small enough to run on a laptop CPU. The interesting part isn't
that it works — it's how little of the output the model is trusted
with.

What DiffScribe does

Stage some changes, run one command:

python3 -m diffscribe draft

It parses the diff, builds a compact digest (files, exact +/- counts,
and a few "signal" lines like new function definitions), and asks a
local model — Qwen2.5-0.5B-Instruct (Apache 2.0), served by llama.cpp
(MIT) — for two small wordings: a commit subject, and a handful of
changelog bullets. Then deterministic code takes over again: it
validates both texts, generates the per-file stats body itself, and
assembles the final draft with labels showing exactly which words came
from the model and which came from rules.

The governing rule of the whole design: the model words things; code
counts things. A language model — especially a half-billion-parameter
one — will happily write "+47 −13" whether or not those numbers are
true. So it is never given the chance. Every number in DiffScribe's
output was counted by parsing the diff.

The demo — read it like a skeptic

./scripts/demo.sh drafts for a real staged diff: a README usage
section, a new test file, and a new count_sentences function added to
a toy text-statistics project. Recorded verbatim:

COMMIT MESSAGE:
feat: add docstring for textstat/count.py

Files changed: 3 (+20 -1)
- README.md: +5 -1 (modified)
- tests/test_count.py: +9 -0 (added)
- textstat/count.py: +6 -0 (modified)

CHANGELOG ENTRY (Unreleased):
- Updated README for easy navigation
- Added new installation steps
- Updated tests with new code
- Improved textstat count functionality

Now the honest reading, because this output is good and imperfect in
instructive ways. The subject is well-formed, correctly typed, and
points at the right file — but the diff adds a function, not a
docstring. The bullets are reasonable paraphrases, except "Added new
installation steps": the README gained a usage section, not install
steps. Nothing here is malformed, and nothing is quite fabricated —
it's the confident near-miss of a very small model.

That is exactly the failure profile I designed for. DiffScribe cannot
make a 0.5B model wise. What it can do is bound the blast radius:
validate the shape (conventional-commit format, length caps, bullet
counts), validate the grounding (more on that below), generate every
fact-shaped part itself, and label whatever the model did write so a
human editor — you, before you commit — knows what they're reviewing. A
drafter, supervised. Not an oracle.

How it works

Parse. The unified diff becomes structured per-file changes: path, kind (added/modified/deleted/renamed), binary flag, exact added/deleted counts, and up to three signal lines per file (added lines that open a definition — def, class, export function…). One subtlety the tests cover: a content line can look like a diff header (---deleted text inside a removed string), so parsing keys off the diff --git file boundaries, not vibes.
Digest. The parsed change is rendered to a text digest capped at 1,400 characters. Per-file entries truncate before whole files are dropped, and the exact totals line always survives — the model sees a faithful summary even for a huge diff, while the stats in the final output still cover every file.
Draft. Two separate model calls (subject, then bullets), each with a one-shot format example, greedy decoding — temperature 0, so the demo above reproduces byte-for-byte.
Validate, per text, independently. The subject must match the conventional-commit shape, fit 100 characters, and — the check I'm proudest of — its scope must be grounded: if the subject claims feat(auth):, the string "auth" must appear in a changed file's path or signal lines. Bullets must be 1–6 lines, each ≤ 140 characters. Either text can fail on its own and be replaced by a labeled rule-based draft (type inferred from the change shape, exact stats included) without discarding the other.
Assemble. Stats body from code, wordings from wherever they legitimately came from, everything labeled.

There is also a --no-llm mode that skips the model entirely and emits
the pure deterministic draft — vaguer, and never wrong about the facts.
The full recorded transcript of both modes is demo-output.txt in the
repo.

The run where my model lied with a straight face

The grounding check exists because of a specific, embarrassing run
early in development. My first one-shot example — meant only to teach
the output format — used an auth-flavored sample: a digest about
auth/login.py, subject fix(auth): reject expired tokens during login. I then fed DiffScribe the text-statistics diff, and the model
returned, confidently and in perfect conventional-commit format:

feat(auth): reject expired tokens during login

There is no auth code in that diff. There is no login. The model hadn't
read my diff at all; it had copied my example and changed one word.
Every format check passed. This is the tiny-model failure mode that
matters: not gibberish — gibberish is easy to catch — but fluent,
well-formed, entirely wrong.

Two fixes. The example is now deliberately bland and topically distant
(a README edit), because an example a model might parrot should be one
whose parroting is obvious. And the deterministic grounding check: a
scoped subject whose scope appears nowhere in the diff is rejected and
replaced by the fallback, no matter how pretty it is. There's a
regression test named after the incident
(test_assemble_rejects_leaked_example_subject). The subject in the
demo — slightly wrong about "docstring", but genuinely about this
diff — is what the model produces under those constraints.

A second, quieter reuse bug deserves a sentence: I copied last week's
download script for llama.cpp, and it kept failing with a polite
"Not Found" before a bash -x trace showed why — the asset name in the
URL had a doubled letter (llama-bb11580…), a latent typo that had
been sitting in the old script all along. Inherited code inherits bugs.
It also inherits the ability to find them, because the script was
mine to read. Hold that thought for the next section.

Why open innovation matters

This is the third week I've built on the same openly licensed stack —
open weights, an MIT inference engine, a standard-library-only program —
and DiffScribe is the week the compounding became visible.

Reuse is real when the licenses let it be. The llama.cpp wrapper,
the greedy-decoding discipline, the labeled-fallback pattern, even the
download scripts came straight from my Week 2 and Week 3 entries.
Nothing had to be re-negotiated, re-purchased, or re-permissioned; the
licenses (Apache 2.0, MIT) were the whole conversation. And when part
of what I reused turned out to be buggy, openness was the debugging
tool: the script was a file on my disk, readable to the last character,
fixable in one line.

Open weights change who gets to build. DiffScribe's model is a
~490 MB file I downloaded once. No account, no API key, no per-commit
bill, no terms-of-service roulette about whether my use case is allowed
this month. A student on a metered connection in Ahmedabad and a staff
engineer at a Fortune 500 company get the same artifact — and,
because it's just a file, the same ability to inspect what it is and
pin exactly which version produced an output. My demo reproduces
byte-for-byte because the weights, the engine version, and the decoding
settings are all fixed and named in the repo. That reproducibility is
an open-artifact property; a hosted model that silently changes under
you cannot offer it.

Openness is also a quality strategy. The most important line in
this project is a test that encodes a failure. Small open models fail
in public, cheaply, on your own machine, where you can watch them do it
and engineer around it — validation, grounding, fallbacks. That loop
(watch it fail → bound the failure → write the test) is the actual
craft of building with AI right now, and open tooling makes the loop
tight enough to run in an afternoon.

On this week's theme — Ghost in the Machine — DiffScribe fits on the honouring-the-past side of the brief, and I want to be plain about the limits of that fit: this is not a ghost-story generator, and it is not an ofrenda builder. What it is, is a keeper of a project's past. Every commit is a trace of work already done, and when those traces are written as "fix stuff", that past is effectively lost — the story of why a change was made fades, just as surely as an unrecorded memory does. DiffScribe tries to keep that history legible, drafting the commit message and changelog entry that let a future reader reconstruct what happened and why, from the diff itself. And there is a literal ghost in this machine, too: a half-billion-parameter open-weight model that lives entirely on my laptop, offline, drafting words in the dark with no server and no internet — a small, local presence that remembers how to phrase the past, and forgets nothing it was never sent.

Honest limitations

Validation checks shape and grounding, not truth. The demo subject says "docstring" where the diff adds a function; a bullet says "installation steps" where the README adds usage docs. Plausible near-misses survive every check I have. Read the draft before you commit — the tool assumes a human editor, which is why its outputs are labeled by origin.
Scope grounding is a substring heuristic. It catches wholesale example leakage (its actual job), not subtle irrelevance; a scope of auth would also match a path containing author.
Huge diffs are digested, not read. Past the digest cap, later files are summarized by counts alone; the model's wording may skew toward the early files. The stats body remains exact and complete.
Fallback drafting is deliberately vague (chore: update code (3 files, +20 -1)) — correct about every fact it states, useless as prose. It is a safety net, not a writer.
No partner or hosted technology is used — by design, not omission. The project's entire premise is that this job can be done locally, offline, with openly licensed parts.

Prize Categories

None entered — no partner technology is used, by design (see Honest limitations above). This submission is entered for the overall prize only.

Try it

Repo: https://github.com/swarnnim/diffscribe

git clone https://github.com/swarnnim/diffscribe && cd diffscribe
./scripts/download-llamacpp.sh && ./scripts/download-model.sh
./scripts/demo.sh                       # recorded demo, both modes
python3 -m unittest discover -s tests   # 50 tests
git add -A && python3 -m diffscribe draft   # draft for your own change

Standard library only; the downloads are the single network touch, and
after that DiffScribe will happily draft commit messages on a plane, in
a tunnel, or wherever your git log has been embarrassing you.

DiffScribe was built in the open, from open parts, for the most
open-source month of the year. Week 1 taught me to ship small, Week 2
to keep data local, Week 3 to build the guardrails first. Week 4's
lesson: trust the model with the wording, never with the facts — and
write the test for the day it confuses the two.

SlothPlan: the to-do list that does less

Swarnnim Agnihotri — Sun, 25 Oct 2026 08:32:23 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

The problem

My to-do list has 47 items. Yours probably does too. And here's the dirty
secret of productivity culture: the list isn't the work. Triaging the
list is the work — the staring, the re-ordering, the guilt-math of "is
learning Spanish more important than calling the dentist?" I have spent
entire Sunday mornings reorganizing tasks instead of doing them, which is
just procrastination wearing a planner's clothes.

Every to-do app on the planet answers this with more features: priorities,
tags, Eisenhower matrices, AI scheduling assistants that need your calendar,
your email, your soul, and a $12/month subscription. They make the triage
heavier. Nobody built the app that does the triage for you and then —
this is the important part — tells you to do less.

So for "Slow and Steady" I built exactly that: a tool that rewards
laziness by doing the one piece of work you were avoiding (deciding what
matters), capping your day at three things, and granting you written
permission to delete the rest.

What I built

SlothPlan — a command-line tool where you dump a messy to-do list and
get back three buckets: DO TODAY (max 3, non-negotiable), DEFER
(officially not today's problem), and DELETE (permission granted, let
it go). Each item gets a one-line reason. The judgment comes from a local
open-weight model; the guarantees come from deterministic code.

python3 -m slothplan triage -f my-messy-todos.txt

The twist, same as my Week 2 entry: the model, the inference engine, and
all the code run on your own machine. No account. No API key. No
subscription. Your to-do list — which is, let's be honest, a map of your
anxieties — never touches a network.

The demo (real transcript, unedited)

I fed it a 12-item Tuesday dump. Here is what the recorded run produced
(full transcript in the repo's demo-output.txt — nothing cherry-picked):

=== SLOTHPLAN triage ===
method: rule-based fallback (--no-llm was passed; no model was run)

DO TODAY (max 3) — your only decisions today:
  1. Pay electricity bill, due Friday or they cut the power
     -> looks time-sensitive — it names a deadline, payment, or an urgent event
  2. Reply to Priya about the wedding RSVP — deadline is tomorrow
     -> looks time-sensitive — it names a deadline, payment, or an urgent event
  3. Submit the Hacktoberfest Week 3 entry README tonight
     -> looks time-sensitive — it names a deadline, payment, or an urgent event

DEFER — officially not today's problem:
  4. Call dentist to reschedule the appointment
     -> looks time-sensitive — it names a deadline, payment, or an urgent event [moved from today: the 3-item cap keeps your day lazy]
  12. Call mom back — she called twice today
     -> looks time-sensitive — it names a deadline, payment, or an urgent event [moved from today: the 3-item cap keeps your day lazy]

DELETE — permission granted, let it go:
  10. Delete that crypto spam email from "DOUBLE YOUR COINS"
     -> matches a junk pattern — nothing of value is lost
  11. Reorganize my Netflix watchlist
     -> matches a junk pattern — nothing of value is lost

That's the deterministic mode (--no-llm), and it's the mode I'd actually
use daily: three real obligations surfaced, the dentist and mom politely
bounced by the cap with an explanation, and the crypto spam and the
Netflix-watchlist reorganization sentenced to death. Twelve decisions I
didn't have to make.

Now the confession, because the transcript has two runs and I'm not hiding
the first one: when I let the 0.5B model judge all 12 items itself, it
took "rewards laziness" as a personal mission. It deferred the
electricity bill with the reason "no deadline, start next month" — for
a bill due Friday. It called buying milk "spam". It deleted calling my
mother. Every verdict parsed cleanly — 12/12, zero fallbacks — but its
judgment was a sloth with an agenda. The transcript shows it exactly as
it happened, which is the point of the architecture below: the model's
opinions are suggestions; the deterministic layer holds the guarantees.

How it works

Deliberately boring architecture, because boring ships:

Parsing (stdlib only): every non-empty line is a task; # comments and bullet/checkbox markers are stripped. My sample file's header comment got triaged as a task in the first build — fixed, and there's a test for it now.
Judgment (slothplan/llm.py): one verdict per task from Qwen2.5-0.5B-Instruct (Apache 2.0 open weights, Q4_K_M quantized) through the llama.cpp binary (MIT). Greedy decoding, ~3 seconds per item on two CPU cores. The model emits a single bucket word plus a short reason — a shape small enough for a 0.5B model to hold. This was a discovery, not the plan: my first prototype asked for one big JSON object covering all tasks, and the model hallucinated item numbers 13–20 for a 12-item list and stuffed 12 entries into a 3-item bucket. So the model judges one task at a time, and structure is enforced by code.
Enforcement (slothplan/triage.py): every verdict is parsed and validated. Max 3 in "today" — overflow is moved to defer with the reason printed, so the cap is visible, not silent. Unparseable verdicts fall back to keyword rules and are labeled as fallback in the output. Nothing fails silently, ever.
Zero third-party Python dependencies. Python 3.8, two downloaded files, and it runs. 29 unit tests, all passing.

Why open innovation matters

This tool cannot exist on a closed API, for two reasons — one
practical, one philosophical.

Practically: SlothPlan's entire design is a bet that a small model is
enough. A 0.5B model is honest about what it is — opinionated, sometimes
wrong, occasionally deleting your electricity bill — and the whole
architecture (deterministic guardrails, labeled fallbacks, a --no-llm
mode) is built around that honesty. You can only build that way if you can
run the model locally, iterate on prompts for free at 3 a.m., and ship
something whose marginal cost per triage is exactly zero. A closed API
charges per token, which means every design decision bends toward fewer,
bigger calls — the opposite of this architecture. And a to-do list is
personal enough that "send it to someone's cloud" was never on the table.

Philosophically: the open-weights ecosystem is what lets a student with a
$0 budget and a borrowed VM build something in a day that would have been
a research project five years ago. Qwen2.5's weights are public under
Apache 2.0. llama.cpp is MIT. My code is MIT. Anyone can audit every layer,
swap in a bigger GGUF with one flag, or fork the whole thing. That
composability — weights, engine, and app all inspectable and replaceable —
is open innovation working exactly as advertised. The moat isn't the model;
it's the trust that comes from everything being auditable.

Honest limitations

I'd rather tell you than have you discover them:

The bundled model is 0.5 billion parameters — tiny on purpose, so it runs on any laptop CPU. Its verdicts are opinions, and sometimes bad ones (see: the electricity bill incident). Any GGUF drops in via --model; a bigger model would judge better.
Reasons are sometimes missing ((no reason given)) — the model often emits just the bucket word despite being shown examples.
The rule-based fallback is keyword heuristics, not understanding. It won't catch "renew the thingy before the thing expires."
Prototype built in a day for a challenge, not a hardened product. 24 items max per run, .txt input, CLI only.

Bonus-points honesty: I have no first user yet — this was built for
the challenge this week, starting Monday morning. The demo above is real
output from the actual tool, and the limitations section is real too.

Try it

Repo: https://github.com/swarnnim/slothplan

./scripts/download-llamacpp.sh
./scripts/download-model.sh
python3 -m slothplan triage -f sample_todos/messy.txt

If you also have a 47-item list you're avoiding: what's the one task on
it you'd secretly love an app to delete for you? That's the roadmap —
a bigger delete bucket.

SlothPlan: the to-do list that does less

Swarnnim Agnihotri — Tue, 20 Oct 2026 05:02:46 +0000

SlothPlan: the to-do list that does less

My entry for the Hacktoberfest Week 3 "Slow and Steady" challenge — built for International Sloth Day, with open-weight models, zero API costs, and a philosophy I'd actually live by.

The problem

My to-do list has 47 items. Yours probably does too. And here's the dirty secret of productivity culture: the list isn't the work. Triaging the list is the work — the staring, the re-ordering, the guilt-math of "is learning Spanish more important than calling the dentist?" I have spent entire Sunday mornings reorganizing tasks instead of doing them, which is just procrastination wearing a planner's clothes.

Every to-do app on the planet answers this with more features: priorities, tags, Eisenhower matrices, AI scheduling assistants that need your calendar, your email, your soul, and a $12/month subscription. They make the triage heavier. Nobody built the app that does the triage for you and then — this is the important part — tells you to do less.

So for "Slow and Steady" I built exactly that: a tool that rewards laziness by doing the one piece of work you were avoiding (deciding what matters), capping your day at three things, and granting you written permission to delete the rest.

What I built

SlothPlan — a command-line tool where you dump a messy to-do list and get back three buckets: DO TODAY (max 3, non-negotiable), DEFER (officially not today's problem), and DELETE (permission granted, let it go). Each item gets a one-line reason. The judgment comes from a local open-weight model; the guarantees come from deterministic code.

python3 -m slothplan triage -f my-messy-todos.txt

The twist, same as my Week 2 entry: the model, the inference engine, and all the code run on your own machine. No account. No API key. No subscription. Your to-do list — which is, let's be honest, a map of your anxieties — never touches a network.

The demo (real transcript, unedited)

I fed it a 12-item Tuesday dump. Here is what the recorded run produced (full transcript in the repo's demo-output.txt — nothing cherry-picked):

=== SLOTHPLAN triage ===
method: rule-based fallback (--no-llm was passed; no model was run)

DO TODAY (max 3) — your only decisions today:
  1. Pay electricity bill, due Friday or they cut the power
     -> looks time-sensitive — it names a deadline, payment, or an urgent event
  2. Reply to Priya about the wedding RSVP — deadline is tomorrow
     -> looks time-sensitive — it names a deadline, payment, or an urgent event
  3. Submit the Hacktoberfest Week 3 entry README tonight
     -> looks time-sensitive — it names a deadline, payment, or an urgent event

DEFER — officially not today's problem:
  4. Call dentist to reschedule the appointment
     -> looks time-sensitive ... [moved from today: the 3-item cap keeps your day lazy]
  12. Call mom back — she called twice today
     -> looks time-sensitive ... [moved from today: the 3-item cap keeps your day lazy]

DELETE — permission granted, let it go:
  10. Delete that crypto spam email from "DOUBLE YOUR COINS"
     -> matches a junk pattern — nothing of value is lost
  11. Reorganize my Netflix watchlist
     -> matches a junk pattern — nothing of value is lost

That's the deterministic mode (--no-llm), and it's the mode I'd actually use daily: three real obligations surfaced, the dentist and mom politely bounced by the cap with an explanation, and the crypto spam and the Netflix-watchlist reorganization sentenced to death. Twelve decisions I didn't have to make.

Now the confession, because the transcript has two runs and I'm not hiding the first one: when I let the 0.5B model judge all 12 items itself, it took "rewards laziness" as a personal mission. It deleted the electricity bill. It called buying milk "spam". It deleted calling my mother. Every verdict parsed cleanly — 12/12, zero fallbacks — but its judgment was a sloth with an agenda. The transcript shows it exactly as it happened, which is the point of the architecture below: the model's opinions are suggestions; the deterministic layer holds the guarantees.

How it works

Deliberately boring architecture, because boring ships:

Parsing (stdlib only): every non-empty line is a task; # comments and bullet/checkbox markers are stripped. My sample file's header comment got triaged as a task in the first build — fixed, and there's a test for it now.
Judgment (slothplan/llm.py): one verdict per task from Qwen2.5-0.5B-Instruct (Apache 2.0 open weights, Q4_K_M quantized) through the llama.cpp binary (MIT). Greedy decoding, ~3 seconds per item on two CPU cores. The model emits a single bucket word plus a short reason — a shape small enough for a 0.5B model to hold. This was a discovery, not the plan: my first prototype asked for one big JSON object covering all tasks, and the model hallucinated item numbers 13–20 for a 12-item list and stuffed 12 entries into a 3-item bucket. So the model judges one task at a time, and structure is enforced by code.
Enforcement (slothplan/triage.py): every verdict is parsed and validated. Max 3 in "today" — overflow is moved to defer with the reason printed, so the cap is visible, not silent. Unparseable verdicts fall back to keyword rules and are labeled as fallback in the output. Nothing fails silently, ever.
Zero third-party Python dependencies. Python 3.8, two downloaded files, and it runs. 29 unit tests, all passing.

Why open innovation matters

This tool cannot exist on a closed API, for two reasons — one practical, one philosophical.

Practically: SlothPlan's entire design is a bet that a small model is enough. A 0.5B model is honest about what it is — opinionated, sometimes wrong, occasionally deleting your electricity bill — and the whole architecture (deterministic guardrails, labeled fallbacks, a --no-llm mode) is built around that honesty. You can only build that way if you can run the model locally, iterate on prompts for free at 3 a.m., and ship something whose marginal cost per triage is exactly zero. A closed API charges per token, which means every design decision bends toward fewer, bigger calls — the opposite of this architecture. And a to-do list is personal enough that "send it to someone's cloud" was never on the table.

Philosophically: the open-weights ecosystem is what lets a student with a $0 budget and a borrowed VM build something in a day that would have been a research project five years ago. Qwen2.5's weights are public under Apache 2.0. llama.cpp is MIT. My code is MIT. Anyone can audit every layer, swap in a bigger GGUF with one flag, or fork the whole thing. That composability — weights, engine, and app all inspectable and replaceable — is open innovation working exactly as advertised. The moat isn't the model; it's the trust that comes from everything being auditable.

Honest limitations

I'd rather tell you than have you discover them:

The bundled model is 0.5 billion parameters — tiny on purpose, so it runs on any laptop CPU. Its verdicts are opinions, and sometimes bad ones (see: the electricity bill incident). Any GGUF drops in via --model; a bigger model would judge better.
Reasons are sometimes missing ((no reason given)) — the model often emits just the bucket word despite being shown examples.
The rule-based fallback is keyword heuristics, not understanding. It won't catch "renew the thingy before the thing expires."
Prototype built in a day for a challenge, not a hardened product. 24 items max per run, .txt input, CLI only.

Bonus-points honesty: I have no first user yet — this was built for the challenge this week, starting Monday morning. The demo above is real output from the actual tool, and the limitations section is real too.

Try it

Repo: https://github.com/swarnnim/slothplan

./scripts/download-llamacpp.sh
./scripts/download-model.sh
python3 -m slothplan triage -f sample_todos/messy.txt

If you also have a 47-item list you're avoiding: what's the one task on it you'd secretly love an app to delete for you? That's the roadmap — a bigger delete bucket.

Why I put my agent's memory in a graph

Swarnnim Agnihotri — Thu, 15 Oct 2026 16:40:30 +0000

Why I put my agent's memory in a graph

Built for Graph Hacks (WeMakeDevs × FalkorDB) — the project is Trace, a research agent whose memory is a FalkorDB graph.

Every agent I've built has had the same two embarrassing failure modes. First, it forgets. Ask it about the payments outage on Monday, ask again on Thursday, and it stares at you blankly — the conversation is gone. Second, it can't explain itself. When it does answer, you get a confident paragraph with no way to check the work. For a research assistant, those two flaws are fatal.

The standard fix for forgetting is a vector store: chunk everything, embed it, retrieve by similarity. That solves storage but not structure. "Who decided to pause Project Helios, and why?" is not a similarity question — it's a relationship question. The answer lives in a chain: a person made a decision, recorded in a document, motivated by another document. Vectors don't do chains. Graphs do.

So for this hackathon I put the whole memory in a graph.

The design

Trace keeps three named graphs on one embedded FalkorDB instance. Named graphs turned out to be the quiet superpower here: trace_mem_sam is my memory, trace_company is the shared company brain, trace_blackboard is where agents coordinate. Tenant isolation with zero extra code — no WHERE tenant_id = ... sprinkled through every query.

Episodic memory — what happened — is Episode nodes linked by FOLLOWS edges into a temporal chain, with INVOLVES links to the people and systems mentioned. "What did we discuss about the payments outage?" walks the chain and finds the October 10th episode: root cause was the Redis failover, Dev ran the runbook. With a timestamp. That's the whole trick of cross-session memory — it's just a linked list the agent can traverse.

Semantic memory — what is true — is Belief nodes with confidence scores and sources. The part I'm proudest of: beliefs are never deleted. When the team rumor "Helios is cancelled" was corrected to "Helios is paused, not cancelled," the new belief got a CONTRADICTS edge to the old one. The old node stays. Current beliefs are simply the ones with no incoming CONTRADICTS edge. An agent that can't show you what it used to believe — and why it changed its mind — doesn't really have memory. It has a cache.

The blackboard is how two agents coordinate without messaging each other. A planner posts a task, a researcher claims it, findings accumulate as Finding nodes linked by POSTED and ABOUT edges. The handoff chain is itself a traversable path. In the demo, neither the skill graph nor the authorship edge alone could answer "Who knows Redis best?" — PageRank over the skill graph tied across candidates, which the agent says out loud instead of pretending the ranking was decisive. The authorship edge (Ananya wrote the Redis failover runbook) broke the tie. Coordination, not cleverness.

One question, worked end to end

"Who decided to pause Helios, and why?"

The agent finds the decision with a full-text search, then walks the real edges and renders this as the answer's evidence chain:

Person "Priya Nair" -[MADE]-> Decision "Pause Project Helios"
Decision "Pause Project Helios" -[DECIDED_IN]-> Doc "Helios pause RFC"
Decision "Pause Project Helios" -[AFFECTS]-> Project "Helios"

And the "why" comes from the document the decision points to: burn was unsustainable while the team stabilized the ledger after the September incident — plus a second doc the traversal surfaced, Zoya's launch retro, where onboarding leaked 40% of signups. The answer isn't generated and then justified. The path is the answer; the text just narrates it.

My favorite moment in testing was the opposite case: "Is the Postgres upgrade done?" The decision's status is proposed, not accepted — and a seeded memory note says "don't state it as done." The agent answers "No" and cites both. An agent that reads its own memory as a guardrail against hallucination is worth more to me than one more point of retrieval recall.

What FalkorDB specifically made possible

I could have built this on Postgres with a recursive CTE, and for a demo it would have worked. Three things made the graph database the right call:

Named graphs per user. Multigraph isolation meant memory, company knowledge, and agent coordination live side by side with no tenant plumbing.
shortestPath() as an explainability primitive. The evidence chain isn't a feature I bolted on — it's a one-line query. Every answer's "how I got this" is a real path, rendered node by node in the UI.
Algorithms as tools. CALL algo.pageRank('Person','KNOWS') turned "who knows X best" from a vibes question into a computed ranking — with the honest fallback when the math ties.

And pragmatically: FalkorDBLite runs embedded with pip install, no Docker, no server to babysit. The entire demo — database included — runs on a laptop with zero infrastructure. For a four-day hackathon, that mattered more than any feature.

The honest limits

I won't pretend this is a production system. The "LLM" in the demo is a deterministic template composer — it stitches tool outputs into sentences and is physically incapable of inventing facts, which is a feature for a demo and a ceiling for a product. The vector search uses hashed character trigrams, not neural embeddings: it finds text that looks like your query, not text that means it. Question routing is keyword rules, not an LLM classifier. The company is fictional. The scale is dozens of nodes, not millions.

But the core bet survived contact with reality: when memory is a graph, remembering and explaining become the same operation — a traversal. The agent doesn't retrieve context and then reason about it. It reasons by traversing. That's the idea I'd keep, whatever the scale.

Trace was built during Graph Hacks (Oct 15–18, 2026). AI coding assistants wrote the implementation under my direction; the architecture, data model, and every design trade-off above are mine. 39/39 tests green, $0 spent.

LocalLens: private document Q&A that runs 100% on your machine

Swarnnim Agnihotri — Tue, 13 Oct 2026 05:25:15 +0000

LocalLens: private document Q&A that runs 100% on your machine

My entry for the Hacktoberfest Week 2 "Side Hustle" challenge — built with open-weight models, zero API costs, and a business model I'd actually try.

The problem

Last year a freelancer friend was handed a 34-page client contract and asked to "just flag anything weird" before signing. She couldn't paste it into ChatGPT — the contract literally had a confidentiality clause forbidding exactly that. So she read all 34 pages, twice, on a Sunday.

That's the gap: millions of people handle documents they legally or ethically can't upload anywhere — client contracts, payroll sheets, patient intake forms, HR files. Their choices are manual reading or breaking confidentiality. There is no third option that costs less than a lawyer.

What I built

LocalLens — a command-line tool where you point at a document, ask a question in plain English, and get an answer in seconds. The twist: the AI model, the retrieval, and the inference engine all run on your own machine. No account. No API key. No subscription. Your document never touches a network.

python3 -m locallens ask -f contract.txt \
  -q "What is the notice period for terminating the agreement?"

Real output from the included demo (Qwen2.5-0.5B-Instruct, running on a 2-CPU virtual machine — nothing staged):

Q: What is the notice period for terminating the agreement?

The notice period for terminating the agreement is thirty (30) days.

(answered from sentence(s) [14, 17] of 32 — run with --show-context to see them)

Two things I'm proud of here. First, it cites its sources — every answer tells you which sentences it used, and --show-context prints them, so you can verify before acting on anything. Second, when the answer isn't in the document, it says so instead of inventing one:

Q: What is the penalty for late payment of invoices?

Not found in the document.

For a tool aimed at contracts, that abstention behavior isn't a nice-to-have. It's the whole product. A hallucinating contract assistant is worse than useless — it's a liability.

Who would pay for this, and why

Three personas, all real:

Freelancers and solo consultants reviewing client MSAs and SOWs. They already pay $15–30/month for contract tools that upload their data to someone else's cloud. A one-time $29 purchase that keeps everything local is an easy sell — privacy is the feature, not a checkbox.
Small HR and accounting firms answering "what does the policy say about X?" fifty times a week from employee handbooks and tax documents they can't share externally.
Clinic and legal admin staff triaging intake paperwork and engagement letters under confidentiality obligations.

The business model I'd actually try: open-source core (this repo, MIT), paid packaged apps — a polished desktop build with PDF/DOCX support and multi-document search at a one-time price. The open core builds trust with exactly the audience that cares about where their data goes; the packaging is what they pay for.

Bonus-points honesty: I have no first user yet — this was built for the challenge this week. The demo above is real output from the actual tool, and the limitations section below is real too.

How it works

Deliberately boring architecture, because boring ships:

Retrieval (stdlib only): the document is split into sentences and ranked by keyword overlap with the question — stopword-filtered, with naive stemming and a tight-span tie-break so the most focused sentence wins. No embeddings, no dependencies, runs anywhere.
Generation: the top sentences go into a prompt for Qwen2.5-0.5B-Instruct (Apache 2.0 open weights, Q4_K_M quantized), run through the llama.cpp binary (MIT). Total footprint: ~400 MB, ~20 tokens/sec on two CPU cores.
The whole Python project has zero third-party dependencies. If you have Python 3.8 and the two downloaded files, it runs.

Two setup scripts fetch the binary and the model — both free, no accounts. From zero to first answer takes about five minutes, most of it downloading.

Why open weights made this possible

This product cannot exist on a closed API. The entire value proposition — "your document never leaves your machine" — is only credible because every layer is inspectable: the model weights are public (Qwen2.5, Apache 2.0), the inference engine is open source (llama.cpp, MIT), and my own code is MIT. A privacy tool built on a black-box API is a contradiction; built on open weights, it's a verifiable claim. Anyone can audit exactly what runs. That auditability is the moat — and it's only available because the weights are open.

Honest limitations

I'd rather tell you than have you discover them:

The bundled model is 0.5 billion parameters — tiny on purpose, so it runs on any laptop CPU. It's reliable at lookup questions and honest abstention, but convoluted phrasing can stump it, and questions needing synthesis across distant clauses want a bigger model. Any GGUF drops in via --model.
Retrieval is keyword-based, so pure paraphrases can be missed.
.txt input only in v0.1 — PDF/DOCX parsing is roadmap, not reality.
Prototype, not a hardened product. Verify answers against the cited sentences before acting on them.

Try it

Repo: https://github.com/swarnnim/locallens

./scripts/download-llamacpp.sh
./scripts/download-model.sh
python3 -m locallens ask -f sample_docs/freelance-nda.txt \
  -q "How long do confidentiality obligations survive?"

If you handle sensitive documents for a living, I'd genuinely like to know: what's the one document you wish you could ask questions about but can't upload anywhere? That's the roadmap.