Stimpunks Foundation

Mutual Aid and Human-Centered Learning for Neurodivergent and Disabled People

lush green garden with vibrant red flowers

Start Your Own Knowledge Garden

🗺️

Home » Field Guide » IT » Start Your Own Knowledge Garden

People keep asking how to build what we built. Here is the short answer, the template, and an honest account of which parts travel and which do not.

Our own setup is documented in The Stimpunks Knowledge System. That page is a maintainer’s account of a specific, fairly elaborate thing. This one is the on-ramp: what to actually do on a Tuesday afternoon, starting from nothing.

The template is on GitHub: Stimpunks/knowledge-garden-starter. Folders, one Python script, and a rule about not editing your own sources. No app, no subscription, no account to make.

Take only the steps you need

Five steps, and they degrade gracefully. Most of the value is in the first one, which needs no software at all. Each later step adds convenience on top of something that already worked. Stop wherever it stops being useful — a half-built garden is a garden, not a failure.

We are saying that plainly because the opposite framing is how these things die. A tool that only pays off once you have finished configuring it will be abandoned during configuration, on a bad day, by exactly the person who needed it.

1. Make a garden. No tools required.

This part we have said before, in The Stimpunks Knowledge System as Curriculum:

  1. One folder. Everything they read, save, or write goes in it, untouched.
  2. One index file, listing what’s in the folder with a line about why each thing is there.
  3. A habit of adding to both.

That’s it. That’s a garden. No app, no subscription, no AI.

The template ships those folders already made:

garden/
  raw/      Your originals. NEVER edited, renamed, or reorganised. Kept flat.
  wiki/     Your index. Points at raw/. Regenerated, not hand-maintained.
  notes/    Your live writing. Edit freely — a workspace, not an archive.
  inbox/    Undecided things. Should usually be empty.

One rule makes the whole thing work: never edit anything in raw/. Not to tidy a filename, not to fix a typo. Every derived thing — every summary, category, and index — lives somewhere else and points back. That is the difference between provenance you can cite and a pile you have been quietly rewriting.

You can do this in Finder, in Obsidian, in anything. Put a file in raw/, write a line about why in the index, repeat. The one-click version has its own page: Filling the Garden covers clipping a web article straight into your library with its source URL and clip date intact, writing your notes in Obsidian or Ulysses, and browsing what you have through backlinks and a graph. It needs no terminal either — which is why it belongs here at step one rather than further down the list.

Why bother writing “why this is here”? Because that line is a small act of synthesis, repeated hundreds of times — and it is the exact skill a citation is testing. The index is where the learning shows.

2. Put it in git.

Not for collaboration, and not really for backup. For mercy. Once every version of your thinking is recoverable, you stop being careful with your own work in the way that stops you working. Version control is mercy, made structural.

git init
git add .
git commit -m "My garden, day one"

If you used the template, you already have a repository — skip git init. Cloning gave you one. Running it again is not dangerous, it is just confusing: at the top of your project it prints “Reinitialized existing Git repository” and changes nothing, and inside garden/ it quietly makes a second repository inside the first, so git log there shows a history you do not recognise and git push fails saying there is nowhere to push to. Run git status first — anything other than “not a git repository” means you are set, so use the last two commands and drop the first.

And check which folder you are in before you run any of it. git init followed by git add . in the wrong place — your home folder, say — makes a repository out of everything you own and offers up your SSH keys to be committed along with it. pwd tells you where you are. Of everything on this page that is the one mistake with real consequences, and one command prevents it.

Three commands and you have a history. The template includes a walk-through written for someone who has never opened a terminal — what pwd and ls do, how to drag a folder from Finder instead of typing paths, a table of common stumbles, and an explicit list of the three commands that can destroy work, so you know the ones you are learning cannot.

If someone is teaching you the terminal this week, your own garden is better practice than any exercise. The stakes are real and the thing you end up with is yours.

One warning, once you automate it. A backup on a timer that commits everything will eventually fire while you are mid-thought and save half a change under a message like “Daily backup snapshot.” Ours did exactly that: it captured five newly filed papers and the code that indexed them, but not the paragraph that made them make sense — so for a few minutes our own library held a book while a page insisted we did not have it. Point the timer at the one folder that has no other copy anywhere. Everything else can wait for a commit whose message says what it did.

3. Let something else write the index.

Past a few dozen files, maintaining the index by hand stops being fun. The template’s wiki/_generate.py walks your originals and writes it for you: a front page plus one page per shelf, every entry linking to the real file.

Edit wiki/_config.json — your garden’s name and your own shelves — and run it. Anything whose filename matches nothing lands in Unidentified, which is not a bug. It is your to-do list for the files whose names say nothing about what they are.

The index is disposable; the sources are not. If it comes out wrong, change the config and run it again. Never hand-edit generated pages — your edits get silently overwritten, which is worse than being refused.

4. Make it searchable.

A library you cannot search is half a library, and filenames are a terrible index of meaning. qmd is a local search engine for folders of Markdown — keyword search, meaning-based search, and a reranker, all running on your own machine with no vendor and no network.

The payoff is finding things by what they mean. Ask our garden why everything comes apart when a plan changes at the last minute. A keyword search returns nothing useful, because none of those are the words we use. A search that understands meaning returns our Context Switching Cost pattern and our writing on monotropism — the vocabulary the question was reaching for. A person in distress does not arrive knowing your vocabulary. They arrive saying it hurts.

Print an example query on a public page and your search will start returning the page. Ours does. Describe the question instead of quoting it, or accept that your own writing about the garden is now part of the garden.

One caveat worth knowing before you start: search tools read text, and most research libraries are PDFs. The honest version of that problem is in the template, including the part people skip — not everything extracts, and a tool that does not say so will let you conclude your garden is silent on something it simply could not read. In ours, 269 of 354 stored files yield any text at all. The rest are images, video, and cloud-document pointers that no extractor can read, and we would rather print that fraction than imply full coverage.

5. Concepts — only if you already have a vocabulary.

Our system has a layer that indexes ideas rather than files: one page per concept, gathering everything the whole garden holds about it. It works because it keys on our glossary — 445 terms we already maintained in public.

This is the one part of the pattern that does not travel, and the template deliberately leaves it out. Without a controlled vocabulary there is nothing for it to key on, and asking a machine to invent one is how you end up with a taxonomy nobody believes — including you. If you want this layer, the honest first step is not a download; it is deciding what your words are.

One rule if you build it anyway: never cite a concept page. The synthesis on ours is written by a machine reading our own shelves. That makes it a lead worth following, not evidence worth quoting. Our garden spider is required to open the human-authored source underneath and cite that instead — because a confident paragraph assembled by a language model is precisely what the never-edit-your-originals rule exists to keep out of a citation. Machine-written navigation is a real convenience. It is not a source, and the moment it is treated as one, the provenance you built the whole thing to protect is gone.

What this will not do

It will not create capacity. It stops you wasting the capacity you have on finding things you already had.

It is not a productivity system. Nothing in it counts your output or asks you to keep a streak. We are wary of techno-solutionism and we are not going to pretend a folder structure fixes anything structural.

And the part that reports your gaps can be broken too. We built a check to tell us when a page’s writing had gone out of date. It reported all clear twice while two of our pages sat there insisting we did not own books we had just filed. The first version measured the wrong thing — it watched for a large change in how many sources a page had, and gaining one book moves that by under one percent. The second reset the record it was measuring against every time anything was added, so it could never fire at all. Both times something unrelated exposed it. A check nobody has watched fire should be assumed broken. Go and break something on purpose, and make sure it complains.

And it will not stay tidy. Ours does not. The index mis-files things, a search index reflects the last time you rebuilt it rather than what is on your disk, and the Unidentified pile refills every time we add something whose filename says nothing about what it is. We cleared ours to zero this month. We do not expect it to stay there, and that is fine — a garden that admits its gaps is more useful than one that looks finished.

Credit

The source-plus-index pattern is not ours. It comes from Andrej Karpathy’s llm-wiki. Search is tobi/qmd. What we added is the access argument: that institutional memory is infrastructure, that a knowledge base which only works when one person is at full strength is not a knowledge base, and that originals stay untouched because we get cited.

Default to open. Steal all of it.