llm-wiki

llm-wiki.md

LLM Wiki

A pattern for building personal knowledge bases using LLMs.

This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.

The core idea

Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.

The idea here is different. Instead of just retrieving from raw documents at query time, the LLM incrementally builds and maintains a persistent wiki — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then kept current, not re-derived on every query.

This is the key difference: the wiki is a persistent, compounding artifact. The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.

You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.

This can apply to a lot of different contexts. A few examples:

• Personal: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
• Research: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
• Reading a book: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like Tolkien Gateway — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
• Business/team: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
• Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives — anything where you're accumulating knowledge over time and want it organized rather than scattered.

Architecture

There are three layers:

Raw sources — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.

The wiki — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.

The schema — a document (e.g. CLAUDE.md for Claude Code or AGENTS.md for Codex) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.

Operations

Ingest. You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.

Query. You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: good answers can be filed back into the wiki as new pages. A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.

Lint. Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.

Indexing and logging

Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:

index.md is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.

log.md is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. ## [2026-04-02] ingest | Article Title), the log becomes parseable with simple unix tools — grep "^## \[" log.md | tail -5 gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.

Optional: CLI tools

At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. qmd is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.

Tips and tricks

• Obsidian Web Clipper is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
• Download images locally. In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. raw/assets/). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
• Obsidian's graph view is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
• Marp is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
• Dataview is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
• The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.

Why this works

The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.

The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.

The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.

Note

This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.

A different bet on the same problem, in case the contrast is useful.

Instead of an LLM that maintains markdown pages, I run a local store where maintenance is deterministic and never calls a model. One Rust binary, local Qdrant, local ONNX embeddings plus a cross-encoder reranker, exposed over MCP so Claude Code reads and writes it on its own.

The part that maps onto the problems in this thread is the write path.

When a new fact contradicts a stored one on the same subject and predicate, the write resolves the conflict right there instead of adding a second truth. An entrenched fact (dependants, confirmations, age) holds; a strong fresh one flips it and demotes the loser to a hidden stale; a borderline one is marked contested or diverted to quarantine. Nothing is deleted, so the audit log keeps the loser.

Two rules keep it from ossifying. Facts carried into a session from memory count at half weight and cannot co-confirm each other, so an old belief can't vote itself into certainty by agreeing with its own echo. And an entrenched fact retrieved in contexts that have drifted from where it was learned loses ranking weight until a fresh in-context confirmation. Predicates can be declared temporal, so a superseded value stays queryable by date rather than being overwritten.

That handles the duplicate and staleness classes at write time rather than in a lint pass, at zero token cost, which also sidesteps the concurrent-ingest forking @huachen-wang described without needing a claim protocol. The tuning constants behind those rules are still being calibrated, so treat the shape as the claim, not the numbers.

Where it lands against your layer 2 is more specific than I expected, and I had to measure my own store to say it honestly rather than from memory of my own design.

Synthesis does happen on the way in. Agents write long structured documents, not one-line facts. The store then destroys the page. Every record is a chunk capped around 600 characters, tied to its siblings by nothing but a source tag, and the chunk carries no order field. One 470KB document sits in there as 1082 fragments reassemblable only by insertion timestamp. There is a read surface, so the structure is visible and browsable, but the page is not.

So the durable object is what differs, and I think that is the real fork in the road. Yours is a maintained page, rewritten as new sources arrive. Mine is a chunk, and nothing reassembles or rewrites anything above chunk level; the conflict machinery above runs on facts, not on prose.

Which leaves the question I can't answer from my side. Is the durable page worth what it costs to keep durable? I get conflict resolution for free and give up ever reading back what was written as a document. You get a document that stays true and pay a model pass for every update. Has anyone run both layers together, a deterministic fact store as the substrate with a maintained wiki as the read surface over it?

Code, if anyone wants to pick at the mechanism: https://github.com/madgodinc/mgi-mind

can we get some more wiki's in here guys, thanks

I built a custom ontology manifest for this pattern, specifically designed for software organizations:

@equationalapplications/schema-software-org
(available on GitHub and npm).

It acts as the schema layer mentioned in the gist and includes:

• 17 node types (like software_application, service, design_spec, and handoff)
• 40 edges (like dependsOn, specifies, and documents)

It's entirely data-driven (no runtime code) and is designed to be passed directly into a core wiki memory instance to act as a disciplined schema for executive agents. Might be useful for anyone trying to adapt this pattern for an internal team or business wiki!

Hi everyone,

I packaged a lightweight implementation of the LLM Wiki pattern so it can be installed through Microsoft APM and initialized with a single command.

The idea is essentially to turn the LLM Wiki pattern into an installable, reusable primitive for coding agents, with QMD support via MCP for local search.

https://github.com/dsissoko/apm-llm-wiki

FrameCode VibeWork

Markdown-First Declarative Governance for AI-Assisted Software Development

Scoped planning · regression protection · selective context · controlled technical memory

View repository · New release · v0.15.0

---

Very cool!
Interesting parallels, too -- I started iterating on https://github.com/nfeldman/amanuensis in March and made a public version in April or May. The conceptual overlap is not exact but the ideas rhyme nicely.

Amanuensis changes the starting point. An agent begins with a durable account of what the code does, why that account is believed, what changed, what is now stale, which findings survived challenge, and which questions are still open.

Hi Andrej,

I came across your LLM Wiki idea and it strongly resonated with something I've been building and learning through.

I've been experimenting with a project called MCMA-OpenMemory:
https://github.com/jimmybackend/MCMA-OpenMemory

I took a slightly different direction: instead of making the generated wiki itself the primary durable object, I'm exploring a user-owned memory layer underneath the AI.

The memory is file-first, encrypted, portable across storage providers, and keeps provenance, validation, confidence and freshness information. Exact reusable memory is checked first, semantic retrieval is optional, and the AI/model can be replaced without changing ownership of the memory.

My thought is that an LLM-maintained wiki like the one you describe could eventually be a derived/readable view over this kind of memory substrate rather than the only persistent representation.

I'm a backend developer exploring this experimentally, so I may be missing important things. I'd genuinely appreciate criticism of the idea, especially whether separating durable memory from the generated wiki seems useful or unnecessarily complicated.

Thanks for sharing the idea file — it helped me think about this problem much more clearly.

Follow-up on the project wiki that quizzes you back — this round's lesson is that the harnesses move under you, and the failure is always silence.

Codex Desktop relocated its data per account. It exports CODEX_HOME only to the processes it launches, so a capture daemon pinned to ~/.codex kept succeeding against a directory Codex had stopped writing to. The only symptom was "nothing captured in 11 days". Fix: discover homes by what's inside them (a sessions/ dir, a state_*.sqlite), never by name, and de-duplicate by inode — the migration had hardlinked the old rollouts into the new home, and a path-keyed queue would have filed every conversation twice. Restarting on the fix recovered exactly the 6 sessions the analysis said were missing.

OpenCode's ids stopped being chronological on 2026-08-14. Its identifier packs timestamp*4096 into 48 bits, so the prefix wraps every ~795 days; ids minted after the wrap sort below every earlier one, and any id > watermark cursor skips the rest of an older session forever. If you sort or bound anything by those ids, check your data — the wrap already happened.

Claude Code added a fifth SessionStart source (fork). An enumerated hook matcher is an exact string list, so forked sessions had been getting no cold-start context. The general lesson: a matcher that lists sources fails closed on the one the harness adds next.

And the meta one: the engine had been telling the model about updates at session start, which is not the same as telling the person. v0.12.0 renders it where you actually look — a hook system message in Claude Code / Codex, a toast in OpenCode, one stderr line before any command.

Still markdown as the source of truth, local-first, no MCP, no build step, three harnesses.

https://github.com/suwonleee/llmwiki/releases/tag/v0.12.0

Noob question here - is there any way that once this is built it could be portable and run without an internet connection on a laptop? Application I am thinking about is building an expert system that could be queried when off the grid without internet connection.

I totally get that updating it would require connection.

Yes, Obsidian works offline, no network connection required.

And you don't need an internet connect to query it if you're using a local LLM ;)

This is a very good article and guideline for the Second Brain Wiki.
I will take especially the "Examples" section as new use cases. As I already figured out my own LLM wiki and use it almost daily right now.

Btw I built a custom connector, in a way of an MCP server, that connects to your second brain repository when you have it on GitHub. Pretty useful because ChatGPT and Claude Web App can then access your second brain. I did a video on that if you are interested.

The repo is open source, so feel free to instanciate it for you:

https://github.com/manuelblinkert/second-brain-github-mcp

how do you guys plugin more than 1 modal to this, like use chatgpt same time with claude?
i've asked chatgpt for answer, it said that put AGENTS.md beside with CLAUDE.md, then both of them have to go through layer that contain SYSTEM.md (for common instruction), WORKFLOW.md (common workflow), RULES.md, MEMORY.md (persistant project context), DECISIONS.md (architectual decisions), TASK.md (task state), along with skills folder and agents folder (architect.md, researcher.md, maintainer.md)

Very cool stuff!

I went and built it.

I'd been re-pasting the same PDFs into chat windows for months, so "nothing is built up" landed hard. I implemented the pattern as a hosted service: raw/ wiki/ schema/, ingest/query/lint, exposed over MCP so Cursor, Claude Code and Claude.ai all read and write the same wiki.

Four things that weren't obvious until I built it:

"Pending ingest" is better as a computed state than a flag. A source with no wiki page linking back to it is pending. It can't drift out of sync, and it lets the agent answer "what should I do next?" without being told.

The rules belong in the knowledge base, not the system prompt. schema/ is just a page the user can edit, and the first tool is get_instructions, whose description tells the model to call it before writing anything.

Citations are links. Parsing [@citekey] into the same edge table as [[wikilink]] gave backlinks, the graph, pending-state and lint checks for free — one mechanism, four features.

MCP is pull-only, so a button on a web page can't make Cursor run an ingest. That forced a second path: a server-side agent running the same six tools.

Hosted at https://wikibrain.app/. Source is AGPL at https://github.com/wikibrain-app/wikibrain if you'd rather run it yourself.

Cortex: a Git-backed memory server that verifies what it cites

We have been building a production-oriented version of this pattern at Obelyth:

Obelyth/Cortex

Cortex is a self-hosted memory system for a private Markdown knowledge base. Git owns the durable notes, every note write becomes a commit, and an MCP server makes the same memory available across compatible AI clients.

The part we kept running into was trust.

A compiled wiki can become confidently wrong. Once an unsupported answer is filed back into memory, later agents can treat the fabrication as a source. Cortex therefore treats model output as untrusted input and surrounds it with narrower, deterministic checks.

brain_ask reads a bounded pack of actual notes, asks a reader model, then checks the quoted evidence against the cited file at the corpus commit. A verified quote proves that the text exists there. It does not pretend to prove that the source is true or that the answer follows from it. Corrected, superseded, ambiguous and missing evidence receive different visible outcomes.

Writes also depend on who is asking. Trusted clients receive the complete toolset. A guest receives only a scoped ask tool and a proposal tool. A guest proposal cannot commit a note. A trusted user must review and accept it first.

For retrieval, we retired ranking over generated one-line index summaries. The navigational index remains, but the production shortlist uses BM25 over full note text under explicit context budgets. The repository includes a retrieval harness that pins evaluations to a corpus commit and reports rank recall, strict phrase recall, pack size and named misses. A new deployment inherits none of our measurements and must establish its own.

Cortex also maintains working context separately from durable notes, assembles cited project handoffs, builds derivable graph edges, and surfaces stale verification stamps, correction chains, superseded links, secret-shaped text and other maintenance problems through an operations dashboard.
What it does not yet have is equally important: it is not currently a complete raw-source compiler like the ingest flow proposed in this gist, it is not an offline-first local-model application, and named collaborator permissions remain future work.

The DOC.HTML proposal in this thread is interesting to us, particularly its section manifests, character budgets and per-section witnesses. Our current view is that HTML should first be tested as a derived verification and selective-hydration format. Git-backed Markdown remains the canonical source until another representation wins on recall, token cost, latency and failure behavior.
I would especially value criticism from anyone who has measured long-lived memory poisoning, section-level hydration, or contradiction handling on a real evolving corpus.

@tungxeodesign-ui

The short answer is: do not synchronize the models with each other. Put the memory outside them, then connect each model to the same memory service.

AGENTS.md and CLAUDE.md are useful, but they are client-specific instruction files. Merely placing them beside each other does not give ChatGPT and Claude shared context. Building parallel stacks of SYSTEM.md, MEMORY.md, TASK.md, and similar files can also create duplication and drift.

The architecture we use with Cortex is:

1. One canonical, Git-backed Markdown corpus.
2. One MCP server in front of it.
3. Thin client-specific instructions telling each model how to use the same tools.
4. Every new session reads shared context, then writes durable results back to the corpus.

Claude Code can use CLAUDE.md. Codex can use AGENTS.md. ChatGPT can connect through MCP where that integration is available. Those files are adapters, while Cortex is the shared memory layer.
Both models can use Cortex simultaneously, but they share durable state, not a hidden live conversation. If Claude records a decision, ChatGPT sees it when it next queries Cortex. For safer collaboration, trusted clients can write directly while guest clients can only ask questions and propose changes for human review.

Simultaneous writes still require normal conflict handling. A conservative setup gives one client trusted write access and lets the others submit proposals.

That is the core idea behind Obelyth Cortex: one memory service, multiple model adapters. OpenAI also documents remote MCP servers for ChatGPT integrations.

So I would simplify the proposed structure to this:
One canonical memory layer, thin instructions for each client, and MCP as the shared interface.

I’ve been using AI coding assistants a lot recently, and I kept running into the same frustrating wall: context drift.

Agents are great at reading syntax, but they are completely blind to architectural intent. They don’t know why a specific pattern was used, why a legacy workaround exists, or what the unwritten rules of a module are. As a result, they frequently propose syntax-correct diffs that quietly break architectural constraints.

I built Repocodex (https://github.com/azaylamba/repocodex) to fix this by giving AI agents a long-term memory for architectural rationale that lives right where the code does.

How it works: Instead of relying on external wikis (which agents don't read) or bloating the codebase with massive docstrings, Repocodex binds "why" context natively to the git tree using the okf-v0-2 knowledge format.

Under the hood, it does a few specific things:

Git-Native Anchoring: Rationale is stored alongside the code. When you branch, merge, or revert, the context travels with the code state.

Pin Checks & CI Attestation: This is the most important part. Code changes, meaning documentation usually rots. Repocodex uses pin checks to tie rationale to specific code states. If the underlying code is modified, the CI attestation fails, flagging that the agent (or human) needs to update the rationale to match the new reality.

Agent-Ready Ingestion: It’s built in Python with a clean CLI, making it trivial to pipe into terminal-first agent workflows or MCP (Model Context Protocol) servers before an agent attempts a refactor.

The Trade-off: The alternative to this is just stuffing everything into massive system prompts or letting RAG guess what context matters. I opted for explicit, deterministic context binding because, for architectural constraints, precision matters more than semantic similarity.

I'd love to hear your thoughts on the approach, especially from anyone else building tooling for agentic workflows or struggling with LLM-induced regressions.

Thanks!

I've been building this LLM wiki thing for a while. I'd learn a ton of stuff talking to LLMs, and none of it stuck, so this pattern (LLM incrementally maintaining a wiki instead of one-off chats) is what got me going, and I built Eigma around it: it turns your chat history into an actual wiki, and layers spaced-repetition style quizzes on top so you actually retain it and build up your own knowledge system instead of just accumulating notes.

It's completely free right now, connects via MCP to your own ChatGPT/Claude. Would really appreciate anyone giving it a try and telling me what's broken: https://eigma.app/

MindBase 0.4.5 — five changes that came straight out of this thread

Following up on my earlier comments. This release is entirely things people raised here about keeping the wiki honest:

1. Sources vs. wiki are separate retrieval layers. Your own notes / imports are indexed as source, AI-written pages as wiki. Answers prefer your material and every citation is tagged so you can see which is which.
2. [@path] citations on every page the LLM writes, added deterministically even when the model forgets. Pages without a source and sources never cited are lint findings computed in code, not by the model.
3. Evidence-verified lint. Contradiction / stale findings must carry verbatim quotes; the server checks each quote against the page and drops findings that don't hold up. Cards show ✓ verified per quote.
4. Free-text captures land in your layer first (sources/contributors/<you>/<date>.md) before the wiki is touched, so nothing the LLM writes is un-citable.
5. Duplicate-page guard + "state rule" — the maintainer can't create a page that already exists (case/separator-insensitive), and prompts document the shape of things, never live values like SHAs or counts.

Tested with qwen3:14b locally: a fresh capture → research page with citation → lint catches the stale claim it contradicts, with the quote.

Repo (MIT): https://github.com/frankchu91/mindbase-llm-wiki

Here's an implementation of this pattern I maintain (mine, MIT): https://github.com/sidleo/llm-wiki

It follows the ingest / query / lint + index / log operations as written, and pins down the two things the gist deliberately leaves to each agent:

• The format is a spec, not a convention. Pages are strictly OKF v0.2 (type-required frontmatter, no custom fields), so a bundle written by one agent stays readable by any other tool — the schema doesn't rot into a per-project dialect.
• Write rules are declared per directory. Each directory's AGENTS.md says which concept types need human confirmation; anything written without it is marked unverified instead of quietly becoming an established "fact". Reading a page surfaces its backlinks automatically, and lint treats a broken link as unwritten knowledge to file, not an error.

One core library, three hosts (DSH plugin / pi extension / skill + CLI), plus Git and cloud-drive sync for sharing a bundle across machines and teammates.

Curious whether others have hit the same wall: the format is easy to get right, the write gate is where it gets contentious.

For what it is worth, in designing a better memory for long-running agents, I've learned a few things, in no particular order:

• Some formatting must be enforced. If you allow the agent to write .md files directly, some models will do as they are told with respect to a date header, etc., others won't. Even if you define a memory type or a status, some will use it correctly, others will ignore it. If you want a few specific fields in a particular format, either add them programmatically (like the current date) or make them required parameters in the tool call.

• Markdown files are great, as long as your context engine is designed to eject old/duplicate copies: Model reads file. Changes it. Reads another part. Changes it. Reads it. Appends to it. The context quickly becomes full of multiple versions of the same file.

• Some editing tools are byte-oriented, and they are very inefficient for manipulating md files. Some editing tools require an exact match to search/replace text. It seems straightforward, but things like different encodings, line breaks, and multiple versions in the context can be problematic. I've watched a model read the file, get the "find" part wrong, read the file again, try again, and it ends up just thrashing around and chewing through tokens until it (hopefully) hits a limit. Line-number-based tools seem to work best.

• Vectors, embeddings, etc. are cool, and there is no doubt in my mind that they are useful for RAG or where the LLM needs to search through new information. However, I've been able to get good results without it by combining:

a) Basic keyword search
b) Instruct the LLM and allow it to set a list of keywords that, when present in a message, result in a RAG-like addition to the context
c) Instruct the LLM and allow it to set tool names or tool prefixes that result in the same

For example, my agent that handles email triage will tag the data such that when an email MCP tool is used, relevant data is automatically pulled into the context. Another agent tags information on how I want weather presented so that whenever it uses a tool to retrieve the forecast, the instructions are automatically pulled in.

To be clear, I'm not claiming this is better than vectors, but it gets the job done quite well without requiring a vector database, embeddings server, etc.

• Periodic message scans and consolidation: I've found that providing the model with memory tools and instructions on how to use it works reasonably well. But, every so often, a model fails to recognize that it should add something to memory, or ends up with conflicting instructions in memory. My solution has been to temporarily maintain a copy of every message and periodically process them to extract additional information that should be in memory and/or resolve conflicting memory info.

Shameless plug for my implementation, once again（再来安利一次我的实现）：https://github.com/ChavesLiu/second-brain-skill
No it's not, and you delu.
The one from Karpathy is a feather.

Link 3.0 is out

Link is local memory for AI agents: plain Markdown files, review-gated writes, no LLM in the memory layer, one store shared by Claude Code, Codex, Cursor, Kiro, Windsurf, Zed, VS Code, Copilot, and Gemini.

What's new:

• Recall works outside English. The tokenizer split on [^a-z0-9]+, so every non-Latin script produced zero tokens: Japanese, Chinese, Korean, Russian, Arabic and Indic memories were unfindable, and nothing said so. Accented Latin was little better: "déploiement" could not be found by typing "deploiement". Scripts written without spaces are now cut into character bigrams (the Lucene CJKAnalyzer approach, no dictionary), Latin accents fold, and combining marks in Indic scripts are kept because they are vowels, not accents; stripping them turned "मंगलवार" into "गलव". Wiki full-text search had the same bug one layer down and is fixed the same way. Found while verifying it end to end: page filenames also slugged non-Latin titles to nothing, so every such memory was filed as memory.md and the second one was refused as a duplicate. A non-English user could save exactly one memory. Titles now keep their own script. ASCII text takes the exact old path, so nothing existing changes: all nine LoCoMo figures are unchanged across 1,536 third-party queries.

• "lnk stale": notice when a memory outlived the code it describes. The most repeated complaint about agent memory is that nothing tells you when a memory stopped being true. A note says the parser lives in a/b.py, the file is renamed, the memory keeps being retrieved and believed. Hosted memory services cannot fix this because they never see the repository. Run "lnk stale" inside a repo and it lists memories naming files git no longer has, with the successor path where git recorded a rename. A path is questioned only when it is missing now and git tracked it before; without the second half, an unresolvable path is just prose and flagging it is the noise that teaches people to ignore the flag. Read-only, findings go to the review gate. Precision is measured, not asserted: 0 false flags across 108 path references in Link's own docs, every probed deletion detected, and the eval fails CI if either moves. Stale memories are also marked in the recall packet, so the agent is told rather than left to trust.

• The retrieval benchmark reports precision, not only recall. Recall is the number this category publishes, and it cannot separate a system that retrieves cleanly from one that returns everything, because returning everything scores 1.0 by construction. On the same 1,536 LoCoMo queries a whole-store dump carries 0.26% signal; Link's top-1 packet reaches 0.3086 precision on the fast tier, 117x, and pays a real recall cost that is published in the same table. The track now reports the ceiling each cutoff allows (evidence sets average 1.53 turns, so nobody can exceed precision@10 of 0.152) and R-precision as the k-independent figure to compare across systems.

• Measured and declined: usage-aware ranking. Four formulations were built and measured (additive frequency, tiebreak-only, recency decay in the Generative Agents form across the recommended 7 to 30 day half-life, MMR diversity) and none ship. Every one either made memories that had gone unread harder to find or did nothing; recency was worst, the old half losing 0.0510 while the fresh half gained 0.0204. The reason is a category difference: those policies suit episodic observation streams, and Link stores durable constraints, which do not become less true for going unread. That is when they most need surfacing. The eval stays in the repo so the next attempt has to clear the same bar.

• "lnk ingest" for structured exports, contributed by @jakobtfaber. Plan-first: provenance manifests hashed per output, staging through a temp directory, validation before promotion, explicit --replace-unmanaged and --prune gates. Imported docs land in the wiki, never in memory, and stay out of personal-memory proposals.

• LinkBar 1.4. Bugs first: health probes ran on the main thread and froze the popover on every Status refresh; the review inbox showed five items and hid the rest; the workspace could not be changed in the shipped app because a Finder-launched app never sees LINK_WORKSPACE. All fixed: probes run concurrently off the main thread, the inbox scrolls, the workspace is chosen in Settings, every approve/archive/accept confirms what it did, and a refused save reports the CLI's real reason. Then the 3.0 tie-in: a Status row runs "lnk stale" against the repo your last agent session was in, with a one-click filter on the Memory tab and an amber dot in the menu bar.

# macOS, CLI + menu bar app
brew install --cask gowtham0992/link/linkbar
lnk setup

# CLI only (or Linux)
brew install gowtham0992/link/link
lnk setup

# already running Link
brew upgrade && lnk setup

# stale check, from inside a repo
lnk stale

Still: every memory a plain file you can open, nothing durable without review, no LLM in the memory layer, CI blocks network code in the runtime.

Release notes: https://github.com/gowtham0992/link/releases/tag/v3.0.0

Repo: https://github.com/gowtham0992/link
Site: https://gowtham0992.github.io/link/
PyPI: https://pypi.org/project/link-mcp/
MCP: https://registry.modelcontextprotocol.io/?q=io.github.gowtham0992%2Flink
Benchmarks: https://github.com/gowtham0992/link/blob/main/benchmarks/RESULTS.md

This is a very powerful paradigm and architectural style. I mainly use OpenCode and want to implement this for that harness, but I don't want to reinvent the wheel if there are existing OpenCode implementations. Are there any implementations that can easily be 'extended' to do so?

@chimezie I built something along these lines (disclosure: I'm the author). Curated Thoughts is an open-source (MIT) desktop app for Linux, macOS and Windows. It keeps a Karpathy-style LLM wiki over a plain-markdown vault, backed by a local SQLite "brain". It also ships an MCP server, curated-thoughts-mcp, so any harness can use it. With 2.12 the server exposes 16 tools, including wiki_context, wiki_search, wiki_traverse_graph, vault_semantic_search, vault_write_note, and a review-before-merge proposal flow for curated "wisdom" entries.

For OpenCode there's now a packaged integration: opencode v0.1.0.

1. Install Curated Thoughts from its releases page. The installers include the curated-thoughts-mcp sidecar. Run the app once to create your brain.

2. Download opencode-0.1.0.tar.gz from the release above, unpack it, and run:

   ./scripts/install.sh                    # preview: prints exactly what it will change, writes nothing
   CT_INSTALL_EDIT=1 ./scripts/install.sh  # apply

   It adds the mcp entry to your global opencode.json without disturbing comments or formatting, installs a small plugin that puts a memory health snapshot in the system prompt, and adds three skills that teach the agent how to use the wiki.

3. Check it with opencode mcp list (should show curated-thoughts connected), or run the bundled doctor for a full diagnosis of sidecar, brain, vault and registration.

If you'd rather wire it up by hand, the core is just an MCP entry:

{ "mcp": { "curated-thoughts": { "type": "local", "command": ["curated-thoughts-mcp", "--mcp"], "enabled": true } } }

On extending it: the integrations repo is MIT and each integration is small. There are sibling integrations for Hermes and DeepSeek Harness if you want to see how the pieces fit. Issues and PRs are welcome.

Thank you and for the info and this implementation