HN Explorer

Show HN: A Karpathy-style LLM wiki your agents maintain (Markdown and Git) (github.com)

260 points by najmuzzaman ↗ HN
I shipped a wiki layer for AI agents that uses markdown + git as the source of truth, with a bleve (BM25) + SQLite index on top. No vector or graph db yet.

It runs locally in ~/.wuphf/wiki/ and you can git clone it out if you want to take your knowledge with you.

The shape is the one Karpathy has been circling for a while: an LLM-native knowledge substrate that agents both read from and write into, so context compounds across sessions rather than getting re-pasted every morning. Most implementations of that idea land on Postgres, pgvector, Neo4j, Kafka, and a dashboard.

I wanted to go back to the basics and see how far markdown + git could go before I added anything heavier.

What it does: -> Each agent gets a private notebook at agents/{slug}/notebook/.md, plus access to a shared team wiki at team/.

-> Draft-to-wiki promotion flow. Notebook entries are reviewed (agent or human) and promoted to the canonical wiki with a back-link. A small state machine drives expiry and auto-archive.

-> Per-entity fact log: append-only JSONL at team/entities/{kind}-{slug}.facts.jsonl. A synthesis worker rebuilds the entity brief every N facts. Commits land under a distinct "Pam the Archivist" git identity so provenance is visible in git log.

-> [[Wikilinks]] with broken-link detection rendered in red.

-> Daily lint cron for contradictions, stale entries, and broken wikilinks.

-> /lookup slash command plus an MCP tool for cited retrieval. A heuristic classifier routes short lookups to BM25 and narrative queries to a cited-answer loop.

Substrate choices: Markdown for durability. The wiki outlives the runtime, and a user can walk away with every byte. Bleve for BM25. SQLite for structured metadata (facts, entities, edges, redirects, and supersedes). No vectors yet. The current benchmark (500 artifacts, 50 queries) clears 85% recall@20 on BM25 alone, which is the internal ship gate. sqlite-vec is the pre-committed fallback if a query class drops below that.

Canonical IDs are first-class. Fact IDs are deterministic and include sentence offset. Canonical slugs are assigned once, merged via redirect stubs, and never renamed. A rebuild is logically identical, not byte-identical.

Known limits: -> Recall tuning is ongoing. 85% on the benchmark is not a universal guarantee.

-> Synthesis quality is bounded by agent observation quality. Garbage facts in, garbage briefs out. The lint pass helps. It is not a judgment engine.

-> Single-office scope today. No cross-office federation.

Demo. 5-minute terminal walkthrough that records five facts, fires synthesis, shells out to the user's LLM CLI, and commits the result under Pam's identity: https://asciinema.org/a/vUvjJsB5vtUQQ4Eb

Script lives at ./scripts/demo-entity-synthesis.sh.

Context. The wiki ships as part of WUPHF, an open source collaborative office for AI agents like Claude Code, Codex, OpenClaw, and local LLMs via OpenCode. MIT, self-hosted, bring-your-own keys. You do not have to use the full office to use the wiki layer. If you already have an agent setup, point WUPHF at it and the wiki attaches.

Source: https://github.com/nex-crm/wuphf

Install: npx wuphf@latest

Happy to go deep on the substrate tradeoffs, the promotion-flow state machine, the BM25-first retrieval bet, or the canonical-ID stability rules. Also happy to take "why not an Obsidian vault with a plugin" as a fair question.

71 comments

[ 3.3 ms ] story [ 249 ms ] thread
dhruv3006
I love that so many people are building with markdown !

But also would like to understand how markdown helps in durability - if I understand correctly markdown has a edge over other formats for LLMs.

Also I too am building something similar on markdown which versions with git but for a completely different use case : https://voiden.md/

kaoD
I'm interested. At a glance this sounds a lot like Hurl[0]. What's the difference?

[0] https://hurl.dev/

goodra7174
I was looking for something similar to try out. Cool!
davedigerati
why not an Obsidian vault with a plugin?
najmuzzaman
Two structural reasons. 1. Obsidian is a single-user editor. It does not have the concept of "agent A drafted this, agent B promoted it, the team approved it." The promotion flow needs a state machine that lives outside the editor. a plugin can simulate it but the source-of-truth has to be a process the agents talk to instead of a vault file. 2. Agents need an MCP surface. An Obsidian plugin API won't do. /lookup, entity_fact_record, notebook_write, and team_wiki_promote are MCP tools the agent runtimes call directly. Obsidian's plugin API targets human users and the Electron app. You would be reimplementing the MCP layer to bridge. Practical compatibility: you can absolutely point Obsidian at ~/.wuphf/wiki/ and use it as a vault (we got someone from our Reddit post do this). Obsidian can be reader while WUPHF stays the writer.
kid64
He presumably wanted the result to be good.
Unsponsoredio
love the bm25-first call over vector dbs. most teams jump to vectors before measuring anything
armcat
Any particular reason for BM25? Why not just a table of contents or index structure (json, md, whatever) that is updated automatically and fed in context at query time? I know bag of words is great for speed but even at 1000s of documents, the index can be quite cheap and will maximise precision
0123456789ABCDE
do you want to pollute the context with blurbs for docs in disparate topics? cascade filtering, even with naïve bm25, helps reduce the amount of _noise_ that's pushed into the context window. if we reduce the amount of results to consider, further filtering or reranking, with more expensive options, becomes realistic. one could even put a cheaper model in front to further clean the results.
imafish
Cool idea. But is anyone actually building real stuff like this with any kind of high quality?

Every time I hear someone say "I have a team of agents", what I hear is "I'm shipping heaps of AI slop".

najmuzzaman
let's talk about real stuff. we built an AI-native CRM backed by HubSpot founder Dharmesh Shah last year before this, had revenue, iterated to focus on context graph infra which looked like the right moat to focus on, did enterprise PoCs, and all of that distilled into this personal project i built on the side to help my own work. turned out to be right interface for making context infra usable.

the team is of 4 HubSpotters who built HubSpot's largest platforms - search, nav, notifs, permissions, AI.

we are in the process of opening up large pieces of our enterprise context architecture to WUPHF and also ship the cloud enterprise version of WUPHF (https://nex.ai/new-home).

portly
I don't understand the point of automating note taking. It never worked for me to copy paste text into my notes and now you can 100x that?

The whole point of taking notes for me is to read a source critically, fit it in my mental model, and then document that. Then sometimes I look it up for the details. But for me the shaping of the mental model is what counts

emsign
Man, there's no point in replying. You are argueing with a non-human therefore the conversation is without meaning and impact and thus a waste of time and energy.
[deleted]
(comment deleted)
arikrahman
I thought this was parody at first as well for a redundant useless product as it was named after the redundant useless product of the same name from The Office (Wuphf.com)
big_man_ting
Totally agree re note taking. We treat our notes way too lightly, just as an attic or a basement leads to hoarding more stuff than you'll ever need.

Most things do not need to end up in your notes, and LLMs add too much noise, one that you likely never personally verify/filter out at all.

JA Westenberg made a good video essay about it a few days ago:

https://youtube.com/watch?v=3E00ZNdFbEk

Bridged7756
Ditto.

It circles back to the question, is this unimportant enough for me to delegate it to a LLM that might get it wrong? If the answer is yes, why even do it to begin with. If the answer is no, you have to do it manually.

I personally though, see value in this type of automation. Stuff like tag categorization, indexing, that otherwise would've been lost seems like a good fit for LLMs. Whether or not they're an ideal solution and something else like a search engine would've been a better fit, is a different question.

anuramat
been thinking the same, but I imagine you could explicitly separate notes and slop, eg something as simple as cron job that goes through all your notes and creates a PR if there's some easy win: typos, inconsistencies, tags, etc

I've been coding like this lately: if I'm too lazy to review a new non-critical section/unit tests, I'll mark it as `// SLOP`; later, if I have to, I'll go through the entire thing, and unmark

shitty tests are better than no tests, as long as you your expectations are low enough

adamsmark
I use my Openclaw setup to record notes I don't ever want to remember the details of. Here are some examples:

Storing my Health Insurance's Member ID, RxBin and other data. Recording the serial number of a product I will be calling technical support for. Organizing files to be more logical and deduplicating or consolidating as needed.

Whenever I want this info, I'll just ask my LLM to pull it up.

batoga
Put AI in your product name, make billion dollars. Put Karpathy in your blog article, get hired by Anthropic as Principal engineer. Milk money as long as fad last. No one is thinking about customer needs, everyone is trying to wash hands in the wave as it last.
najmuzzaman
alright sir/ma'am/neither. we built an AI-native CRM backed by HubSpot founder Dharmesh Shah last year before this, had revenue, iterated to focus on context graph infra which looked like the right moat to focus on, did enterprise PoCs, and all of that distilled into this personal project i built on the side to help my own work. turned out to be right interface for making context infra usable.

not interested in a job at Anthropic as Principal Engineer (i used to be a HubSpot Product Manager with a healthy income, much better than what i am making now, or for the next few years).

took multiple bets and did iterations because we talked to customers and kept evolving while our old competition is still building an AI CRM "in stealth".

been around enough to know waves don't matter but there is still value behind those waves worth extracting away.

vlady_nyz
need to try out asap. love the „the office“ vibe
dataviz1000
LLM models and the agents that use them are probabilistic, not deterministic. They accomplish something a percentage of the time, never every time.

That means the longer an agent runs on a task, the more likely it will fail the task. Running agents like this will always fail and burn a ton of token cash in the process.

One thing that LLM agents are good at is writing their own instructions. The trick is to limit the time and thinking steps in a thinking model then evaluate, update, and run again. A good metaphor is that agents trip. Don't let them run long enough to trip. It is better to let them run twice for 5 minutes than once for 10 minutes.

Give it a few weeks and self-referencing agents are going to be at the top of everybody's twitter feed.

iterateoften
It’s also that agents and ML reach local maximima unless external feedback is given. So your wiki will reach a state and get stuck there.
GistNoesis
The space of self building artefacts is interesting and is booming now because recent LLM versions are becoming good at it fast (in particular if they are of the "coding" kind).

I've also experimented recently with such a project [0] with minimal dependencies and with some emphasis on staying local and in control of the agent.

It's building and organising its own sqlite database to fulfil a long running task given in a prompt while having access to a local wikipedia copy for source data.

A very minimal set of harness and tools to experiment with agent drift.

Adding image processing tool in this framework is also easy (by encoding them as base64 (details can be vibecoded by local LLMs) and passing them to llama.cpp ).

It's a useful versatile tool to have.

For example, I used to have some scripts which processed invoices and receipts in some folders, extracting amount date and vendor from them using amazon textract, then I have a ui to manually check the numbers and put the result in some csv for the accountant every year. Now I can replace the amazon textract requests by a llama.cpp model call with the appropriate prompt while still my existing invoices tools, but now with a prompt I can do a lot more creative accounting.

I have also experimented with some vibecoded variation of this code to drive a physical robot from a sequence of camera images and while it does move and reach the target in the simple cases (even though the LLM I use was never explicitly train to drive a robot), it is too slow (10s to choose the next action) for practical use. (The current no deep-learning controller I use for this robot does the vision processing loop at 20hz).

[0]https://github.com/GistNoesis/Shoggoth.db/

sails
How do you anticipate teams deploying this? I’m wary of GitHub for sensitive business documents, and wonder what an easy secure agent friendly deployment looks like. Cloudflare or GCP are maybe good candidates
frrandias
Hey, contributor to Wuphf here,

Right now this is setup to be run on your machine. Git is used to do versioning but we don't push that to GitHub, nor do we keep any insight into what you have or what you're doing.

If there is long term value people are getting out of Wuphf we'll be happy to build out a hosted business/enterprise compliant version.

LanMeng-LM
Would be great if the provider layer supported arbitrary OpenAI-compatible endpoints — DeepSeek, for example. Any plans?
410298
I no longer can tell if this is satire or not:

https://wuphf.team/

It looks like gastown. Using AI is like children playing with a dollhouse. If it is satire, well done.

Abby_101
The "garbage facts in, garbage briefs out" caveat is the part I'd want stress tested. In my own LLM features the context that decays fastest is what agents wrote without a human glance. Six months in, you have entries that are confidently wrong and the lint pass can't tell which. Does the promotion flow require human review or can agents self promote?
Invictus0
The title of this post doesn't match the repo at all