Build a Private AI Personal Encyclopedia with TypeScript and MDX

Lena: You know, I was looking through my digital archives the other day—years of chats, location history, and random transactions—and it’s just a mess of raw data. It’s like having a library where all the books are shredded on the floor.

Miles: Exactly, and the common mistake is thinking a simple search bar fixes it. But here is the counterintuitive part: research shows that verbose context files can actually reduce an AI's success rate by about 20%. You don't need *more* noise; you need a structured "second brain" that builds itself.

Lena: That is where this private encyclopedia project comes in. We’re talking about a local-first stack using TypeScript and MDX to turn that digital scrapheap into a searchable wiki.

Miles: Right, and we’re doing it with a modular CLI and agent harnesses like Claude and Codex to automate the heavy lifting. Let’s break down how to build this pipeline from scratch.

Lena: So, we’ve established that the goal isn't just to dump files into a folder and hope for the best. We’re building a system that actually understands our lives. But before we get to the AI agents and the fancy wiki rendering, we have to talk about the bedrock. Why TypeScript and why local first?

Miles: You’ve hit the nail on the head. The choice of TypeScript isn't just because it’s popular—it’s about reliability. When you’re dealing with a modular plugin system where different scripts are pulling from your bank statements, your GPS logs, and your old chat exports, you need type safety. You want to know that the data coming out of a "Photos Plugin" matches the schema that the "Wiki Agent" expects. Without those strict interfaces, the whole pipeline becomes a brittle mess.

Lena: It’s like having a standardized shipping container for your data. No matter what’s inside—whether it’s a receipt or a text message—it has to fit the container's dimensions to move through the system.

Miles: Exactly. And the "local first" part is non-negotiable for something this personal. We’ve seen a 340% increase in people searching for self-hosted alternatives to apps like Notion or Obsidian over the last eighteen months. People are hitting "subscription fatigue," sure, but the real driver is privacy. If you’re ingesting your entire location history and every transaction you’ve made in the last five years, do you really want that sitting on someone else’s cloud?

Lena: Absolutely not. Especially when you consider how AI policies change. If a cloud provider decides to train their next big model on your private notes, you’ve lost control of your intellectual property. By keeping everything on your own machine—using a local SQLite database or just structured Markdown files—you’re the only one with the keys.

Miles: And that brings us to the stack. We’re looking at a TypeScript CLI that acts as the orchestrator. Think of it as the air traffic controller. It doesn't do the "thinking"—that’s for the agents—and it doesn't do the "viewing"—that’s for the web frontend. Its only job is to manage the flow. It triggers the plugins to fetch raw data, passes that data to the AI agents for processing, and then saves the result as MDX.

Lena: I love the choice of MDX here. For those who aren't familiar, it’s basically Markdown but with the ability to embed React components. So, your encyclopedia entry isn't just static text; it could have an interactive map showing where you were that day, or a chart of your spending habits, all rendered right inside the page.

Miles: Right, it makes the "encyclopedia" feel alive. But to get there, we need to solve the "single agent" problem. A common mistake people make when they start building AI tools is asking one giant prompt to do everything—fetch the data, analyze it, format it, and write it.

Lena: And that’s where things fall apart, isn't it? The model gets overwhelmed and starts hallucinating.

Miles: Every single time. It’s what experts call the "prompting fallacy"—the belief that you can fix a bad system design just by tweaking the words in your prompt. Instead, we’re going to use a sequential pipeline. One agent per task. It’s a pattern that generalizes to almost any complex AI workflow. If you wouldn't hire one intern to be your accountant, your researcher, and your creative writer all at once, why would you expect one LLM prompt to do it?

Lena: So, the first step for anyone listening is to stop thinking about a "chatbot" and start thinking about a "pipeline." You’re building a factory, not a conversation.

Miles: Spot on. And the first floor of that factory is the modular plugin system. We need a way to ingest those digital archives without rewriting the whole codebase every time we want to add a new data source.

Lena: Let’s talk about that ingestion process. If I have five years of Google Takeout data, a folder of photos, and a bunch of exported WhatsApp chats, how does the CLI actually handle that diversity without becoming a giant, unmanageable block of code?

Miles: This is where the modularity becomes your best friend. In TypeScript, we define a standard `Plugin` interface. Every plugin—whether it’s for "Transactions" or "Social Exports"—must implement a few core methods: `fetch`, `clean`, and `package`. This means the main CLI doesn't need to know *how* to read a CSV from a bank or a JSON from a chat export. It just says, "Hey, Transactions Plugin, give me the cleaned data for July 2025," and the plugin handles the heavy lifting.

Lena: That makes total sense. It’s like a "plug-and-play" architecture. If I decide tomorrow that I want to index my Spotify listening history, I just write a new plugin that matches that interface, drop it in the folder, and the system automatically picks it up.

Miles: Exactly. And because we’re using TypeScript, the CLI can enforce that the output of every plugin is "agent-ready." We don't want to send raw, messy JSON to Claude or Codex. That’s a waste of tokens and a recipe for errors. The plugin’s job is to strip out the noise—the metadata you don't need, the duplicate headers—and turn it into a clean, structured object.

Lena: I’ve noticed in some of the source materials that developers are moving toward this "Gather, Analyze, Recommend, Synthesize" pattern. How does that apply to our ingestion?

Miles: It’s the secret sauce. The plugin handles the "Gather" phase. It pulls the raw data from your local archives. Then, it passes that to what we call "Agent Harnesses." These are specialized wrappers around models like Claude for natural language or Codex for structured data tasks.

Lena: Wait, why use different models? Why not just use the most powerful one for everything?

Miles: Because cost and speed matter, even in a local project. You might use a smaller, faster model to categorize your transactions—something like a "Researcher" agent that just identifies patterns. But when it’s time to actually write the "Year in Review" wiki entry, you bring in a "Writer" agent with more creative nuance. In ADK-TS, which is a framework for this kind of thing, you can actually assign different LLMs to different steps in the sequence.

Lena: So the "Researcher" agent might look at your location history and say, "Okay, Miles was in Tokyo for two weeks in April." Then the "Analyst" agent takes that and cross-references it with his photo metadata to see what he was actually doing.

Miles: Right, and then the "Writer" agent synthesizes that into a beautiful MDX page. But the key is that they communicate through a "shared session state." This is a huge concept in multi-agent systems. The agents don't actually talk to each other directly. Instead, they read from and write to a common "state" object.

Lena: That sounds much cleaner. It prevents that "telephone game" effect where information gets distorted as it’s passed from one person to the next.

Miles: Precisely. If the "Researcher" writes its findings to a key called `raw_location_data`, the "Analyst" knows exactly where to look. We use constants for these keys in our TypeScript code to prevent typos. It’s a small thing, but it’s a "silent killer" in these pipelines. If your researcher writes to `location` and your analyst tries to read from `locations` with an 's', the whole system just sits there with a blank screen and no error message.

Lena: I can see how that would be frustrating. So, step one is defining your "State Keys"—the vocabulary your agents will use to talk to each other through the database.

Miles: Exactly. It’s about building a predictable data flow. You want to be able to look at your "Digital Brain" and see exactly how a raw transaction at a coffee shop turned into a wiki entry about your "Morning Routines of 2025."

Lena: Okay, let’s get into the "brains" of the operation—the AI agent harnesses. We’ve mentioned Claude, Codex, and OpenCode. How are we actually using them to process this data? It’s not just "summarize this," right?

Miles: Not even close. If you just ask for a summary, you get what we call "Wikipedia-style filler." It’s bland, it’s generic, and it misses the personal context that makes an encyclopedia useful. Instead, we use a "Sequential Agent" pattern. Think of it as a four-agent relay race.

Lena: A relay race—I like that. Who’s starting?

Miles: The Researcher is the first runner. Its only job is to look at the raw data from your plugins—say, your chat history from the last month—and identify the "entities" and "events." It’s looking for people you talked to, projects you mentioned, or recurring themes. It uses tools to search through your local files, almost like a specialized search engine.

Lena: And then it hands off the baton?

Miles: Right. It saves its findings to the state, and the Analyst picks it up. The Analyst doesn't look at the raw chat logs—it looks at the Researcher’s findings. Its job is to find the "why" and the "how." It extracts insights, patterns, and statistics. Maybe it notices that you’re most productive on Tuesday mornings after you’ve visited a specific coffee shop, based on your location and transaction data.

Lena: That’s where it starts to feel like a "second brain." It’s connecting dots that I wouldn't even think to look for.

Miles: Exactly. And then the Recommender agent takes that analysis and says, "Based on this, here are the things you should document in your wiki." It prioritizes the most important events. Finally, the Writer agent takes all of that—the raw research, the deep analysis, and the recommendations—and synthesizes it into a polished MDX entry.

Lena: I noticed that some developers use specific instructions to keep these agents from "hallucinating" or going off the rails. For example, telling an agent to "make one search per turn" instead of trying to do everything at once.

Miles: That’s a pro move. Models like GPT-4o love to batch tasks because they think they’re being efficient, but that actually leads to more errors. By enforcing a "one at a time" rule in your agent harness, you ensure that every step is verified before moving to the next. In Part 2 of many professional agent guides, they even suggest adding "callbacks"—little pieces of code that run before and after an agent speaks—to track progress and enforce limits.

Lena: It’s almost like having a project manager for your AI. "Did you finish the research? Great. Now move to the analysis. Don't skip ahead!"

Miles: Exactly. And because we’re using a framework like ADK-TS, this orchestration is handled by the code, not by "prompt engineering." You don't have to beg the model to be organized; the system *forces* it to be.

Lena: It’s also interesting how this handles the "memory" problem. If I’m building a private encyclopedia, I want the system to remember what happened in 2024 when it’s writing about 2025. How do we give these agents a "long-term memory"?

Miles: That’s where the local vector database comes in. Every time an agent writes a wiki entry, we create an "embedding"—a mathematical representation of the meaning of that text—and store it in something like `sqlite-vec`. When the agent starts a new task, it can "query" its own past work. It’s like the agent is looking back through its own diaries to find relevant context.

Lena: So it’s not just reading my files; it’s reading the *encyclopedia* it already built for me. That’s a beautiful feedback loop.

Miles: It really is. It turns a collection of disconnected scripts into a coherent, growing intelligence. And the best part is, because it’s all running on your machine, it’s fast. You’re not waiting for a cloud server to process gigabytes of data.

Lena: Let’s get into the nitty-gritty of the output. We’ve talked about agents and pipelines, but eventually, this all has to turn into files on a disk. Specifically, MDX wiki entries. Why MDX, and how do we ensure they don't just look like a wall of text?

Miles: The magic of MDX is that it allows the AI to "author" UI. When the Writer agent is generating an entry about your recent trip to Tokyo, it’s not just writing "I went to Tokyo." It’s generating a structured file that includes React components. Imagine a line of code like `<TravelMap coordinates={...} />` right in the middle of your notes.

Lena: So the agent is actually "coding" my wiki layout as it writes?

Miles: In a way, yes. We give the agent a set of "allowed components"—sort of like a design system for your digital brain. We tell it, "Hey, if you find location data, use the Map component. If you find financial data, use the Chart component." This is why we use a "template syntax" in our instructions. We provide the structure, and the agent fills in the slots.

Lena: I’ve seen this referred to as "intelligent chunking." How does that help with the MDX generation?

Miles: It’s critical. If you just dump a 50-page PDF into an AI, it’s going to lose the thread. Intelligent chunking means we break that data down into meaningful segments—respecting headings, paragraphs, and natural language boundaries—before the agent even sees it. Each chunk gets a unique ID that links back to the source. So, in your MDX entry, the AI can actually include "Source Traceability."

Lena: "Source Traceability"—that sounds like a fancy way of saying "footnotes."

Miles: Precisely, but automated! You can click a sentence in your wiki, and it will show you exactly which chat message or bank transaction led to that statement. It’s "military-grade" knowledge management. You’re never guessing where an insight came from.

Lena: And since this is all stored as Markdown files on our machine, we’re not locked into any specific app. I could open these files in VS Code, Obsidian, or even a custom web frontend we build ourselves.

Miles: That’s the "digital sovereignty" we’re talking about. In 2025, the average person uses twelve different apps to manage their life. By consolidating everything into MDX, you’re creating a "universal format" for your personal history. You could even use a tool like Pandoc to convert your entire encyclopedia into a PDF book or a website if you wanted to.

Lena: It’s like building a personal Wikipedia that you own. But what about the "Wiki Graph"? I love the idea of seeing how my ideas are interconnected.

Miles: That’s where the "3D force-directed layouts" come in. Since every MDX file can have "bidirectional links"—using the classic `[[WikiLink]]` syntax—you can visualize your knowledge. You might see a cluster of notes around "Productivity" and another around "Health," and suddenly notice a thin line connecting them that you didn't realize existed. Maybe your best coding days are always linked to the days you went for a run.

Lena: It’s revealing the hidden patterns of our own lives. It’s almost like being a data scientist for your own biography.

Miles: Exactly. And because we’re using a local-first stack, that visualization is incredibly fast. You’re not waiting for a browser to fetch thousands of links from a database; it’s all happening right there in your Electron app or your local web server.

Lena: So, the action item here is to define that "Design System" for your MDX. Decide what components you want—maps, charts, code blocks—and then teach your Writer agent how to use them.

Lena: We have the data, the agents, and the MDX files. Now we need a way to actually interact with this encyclopedia. The project uses a TypeScript web frontend and a desktop app. Why go through the trouble of building both?

Miles: It’s about meeting yourself where you are. A web frontend—built with something like Next.js—is great because it’s accessible from any device on your home network. You could be on your tablet on the couch and browsing your digital brain. But the desktop app—likely powered by Electron—is where the "power user" features live.

Lena: Like what? What can a desktop app do that a website can't?

Miles: Native file system access is the big one. If your encyclopedia is going to watch your "Downloads" folder for new receipts or your "Photos" folder for new uploads, it needs to be running as a native process. An Electron app can sit in your system tray, quietly running those "Ingestion Plugins" in the background while you work on other things.

Lena: So it’s like a "silent librarian" always working in the background.

Miles: Precisely. And by using a framework like KnowNote or MarkItUp, which are modern open-source examples of this, you get a polished UI that feels like a professional product, but with 100% of the data staying on your machine. We’re talking about sub-100-millisecond search times because the vector database is sitting on your NVMe drive, not halfway across the world.

Lena: I love the idea of "semantic search" in a personal wiki. Instead of searching for the keyword "coffee," I could ask, "Where was that place I liked in Kyoto?" and it would find it because it understands the *meaning* of my question.

Miles: That’s the power of the "RAG engine"—Retrieval-Augmented Generation—built into the app. When you type a question, the app doesn't just search for text; it creates an embedding of your question, finds the most relevant "chunks" from your MDX files, and feeds them to a local LLM like Ollama to give you a natural language answer.

Lena: It’s NotebookLM, but for my entire life, and without Google watching over my shoulder.

Miles: Exactly. And for the developers listening, building this in TypeScript and React means you can customize every single part of it. Don't like the graph view? Swap it out for a timeline. Want to add a "Quiz Mode" that tests you on your own notes? You just add a new React component to your MDX renderer.

Lena: It’s the ultimate "extensible" system. But I have to ask—is it hard to set up? Most people hear "Docker" or "Vector Database" and they run for the hills.

Miles: That’s the beauty of the latest shift in the tech stack. Projects like KnowNote are "Docker-free." They use SQLite with vector extensions, which means the entire database is just a single file on your hard drive. No complex server configuration, no container management. You just `pnpm install`, `pnpm dev`, and you’re running. It’s democratizing this high-level AI tech for anyone with a laptop.

Lena: That’s a huge relief. It means I can spend more time actually *using* my encyclopedia and less time playing system administrator.

Miles: Right, and that’s the goal. We want to reduce "deployment friction." If it takes three hours to set up, you’ll never do it. If it takes five minutes, it becomes part of your daily workflow.

Lena: Let’s talk about the future-proofing aspect. You mentioned how easy it is to add a Spotify plugin, but how far can we actually take this modular system? What are some of the more "out there" plugins people are building?

Miles: Once you have the core CLI and the agent pipeline, the sky's the limit. I’ve seen people building "Browser History" plugins that use the "Vision" capabilities of models like Claude to actually "see" the websites they visited and summarize the key takeaways. Imagine your encyclopedia automatically documenting every research paper you read online.

Lena: That would be incredible for students or researchers. It’s like an automated bibliography that actually understands the content.

Miles: Exactly. Or think about "Transaction Analysis." Instead of just seeing a list of prices, a plugin could cross-reference your "Transactions" with a "Nutrition" plugin. It sees you bought a specific brand of protein powder and automatically updates your "Health and Fitness" wiki page with the nutritional breakdown and how it correlates to your workout logs.

Lena: It’s about "collapsing the silos." Right now, my health data is in one app, my money is in another, and my thoughts are in a third. The plugin system brings them all into one conversation.

Miles: And the key is the "Common Schema." As long as every plugin outputs data that follows our TypeScript interfaces, the AI agents can connect those dots. You’re building a "Knowledge Graph" that grows more valuable with every new plugin you add. It’s like compound interest for your brain.

Lena: I also like the idea of "Social Exports." In the source materials, there’s mention of ingesting chat history and social media data. That feels like a goldmine for personal history.

Miles: It really is. We often forget the small details of our lives—the jokes we made with friends, the specific advice we gave someone three years ago. A "Social Plugin" can ingest those exports, and the Analyst agent can identify "Recurring Themes" in your friendships or your personal growth.

Lena: It’s almost like a "biographer" that’s been watching you for years. But we have to be careful with "hallucinations" here, right? We don't want the AI to "invent" memories.

Miles: That’s why the "Source Traceability" we talked about earlier is so important. In our plugin architecture, every piece of data must carry its "provenance"—where it came from, when it was created, and who created it. We instruct our agents to *never* make a claim without a corresponding source ID. If the agent can't find a source, it’s not allowed to write it.

Lena: It’s "grounded AI." It’s strictly limited to the facts of your digital archives.

Miles: Precisely. And because you can always click through to the original chat or photo, you have that "sanity check" built in. You’re using the AI’s reasoning power to organize the data, but you’re keeping the "Truth" in the raw files.

Lena: So, the next move for a listener is to look at their most used app—maybe it’s a fitness tracker or a task manager—and think, "How would I write a TypeScript plugin for this?"

Lena: We’ve covered a lot of ground—from the TypeScript CLI to the MDX output and the desktop interface. Let’s boil this down for someone who wants to start building their private encyclopedia today. What’s the "Practical Playbook"?

Miles: Step one: Start with your "Digital Scrapheap." Don't try to index everything at once. Pick *one* data source—maybe your exported Kindle highlights or a folder of markdown notes. Build a simple TypeScript plugin that reads those files and turns them into a clean JSON object.

Lena: Okay, so start small. What’s step two?

Miles: Define your "State Keys." Decide exactly what you want your agents to produce. Do you want "Key Insights," "Action Items," or "Historical Context"? Define these as constants in your code. This is your "Data Contract." It ensures that your researcher, analyst, and writer are all speaking the same language.

Lena: And then we set up the agent pipeline?

Miles: Exactly. Use a framework like ADK-TS to build a "Sequential Agent." Start with a Researcher agent that has access to a `WebSearchTool`—or in our case, a `LocalSearchTool`—to find relevant chunks. Then, add a Writer agent that takes those chunks and formats them into MDX. Don't worry about the Analyst or Recommender agents yet; get the basic "Read data -> Write MDX" flow working first.

Lena: That makes sense. It’s like building the "Minimum Viable Encyclopedia."

Miles: Right. Step four: Choose your "LLM Provider." If you have a powerful machine, download Ollama and run something like Llama 3 or DeepSeek-Coder locally. If you want more "brainpower" and don't mind a bit of cloud interaction, use the Claude or OpenAI APIs. The beauty of our modular architecture is that you can swap these out later just by changing one line of config.

Lena: And for the UI? Should I build a whole Electron app from day one?

Miles: Honestly? No. Start with the CLI. Run your ingestion scripts, and then open the resulting MDX files in an existing tool like Obsidian or VS Code. Once you have a few hundred entries and you start to feel the "limitations" of those tools, *that’s* when you build your custom desktop app or web frontend.

Lena: I love that. It’s "organic growth." You’re building tools to solve your own problems as they arise. What are some "pitfalls" to avoid in this early stage?

Miles: The biggest pitfall is "Prompt Bloat." Trying to put too many instructions into one agent. If your agent's instructions are more than a page long, you need to break it into two agents. Another one is ignoring "Rate Limits." If you’re using cloud APIs, a script that ingests ten years of data can get very expensive very quickly. Always build in "Progress Tracking" and "Callbacks" so you can stop and restart the process without losing data.

Lena: And don't forget the "3-2-1 Backup Rule" we saw in the research. Three copies of your data, two different media types, and one offsite location. Just because it’s "local first" doesn't mean it’s "invincible."

Miles: Absolutely. If your digital brain is your life's work, treat it with that level of respect. Automate your backups with a simple cron job or a shell script that zips up your MDX folder and sends it to an encrypted drive.

Lena: This feels like a project that never really "ends." It just keeps evolving as your life does.

Miles: That’s the point. It’s not a "product" you buy; it’s a "system" you inhabit.

Lena: You know, Miles, as we bring this to a close, I’m struck by how this project is about more than just "organizing files." It’s about "digital sovereignty." In an era where everything is in the cloud and AI models are being trained on our private data, building a local-first encyclopedia feels like an act of rebellion.

Miles: You’ve hit the nail on the head. It’s about taking back control. We’ve spent the last decade giving our data away for the sake of "convenience." This project proves that we can have that convenience—the AI search, the smart summaries, the beautiful visualizations—without sacrificing our privacy.

Lena: It’s a shift from "consumers" to "curators." We’re not just generating content for platforms; we’re building a legacy for ourselves.

Miles: Right. And the tools are finally here to make it possible for anyone with a little bit of TypeScript knowledge. You don't need a team of data scientists; you just need a modular mindset and a few AI harnesses.

Lena: So, to everyone listening, I want you to think about one part of your digital life that feels "unmanageable" right now. Is it your thousands of photos? Your endless chat history? Your scattered project notes? Imagine what it would feel like to have an AI agent go through that mess tonight and present you with a perfectly structured, searchable wiki tomorrow morning.

Miles: It’s a powerful vision. And the best part is, you can start tonight. You don't need to build the whole "Digital Brain" at once. Just build the first plugin. Write the first prompt. Create the first MDX file.

Lena: It’s about that first step toward ownership. I’m definitely going to start by looking at my old travel logs. There’s so much "forgotten" data there that deserves to be part of my encyclopedia.

Miles: I’m going to dive into my old code snippets. Imagine having a "Researcher" agent that can find that one specific function I wrote in 2022 that I know would solve my current problem.

Lena: It’s like having a conversation with your past self.

Miles: Exactly. And your past self has a lot to say, if you just give them a place to speak.

Lena: Thank you for diving into this with me, Miles. This has been a fascinating look at the intersection of AI, privacy, and personal knowledge.

Miles: It’s been a blast. I can't wait to see what people build.

Lena: For everyone listening, take one idea from today—maybe it’s the "Sequential Agent" pattern or the "Modular Plugin" approach—and try to apply it to your own archives. Your digital brain is waiting.

Miles: See what connections you can find. You might be surprised by what’s been hiding in your data all along.

Lena: Thanks for listening. Take a moment to reflect on your own "digital scrapheap" and how you might start taming it today. It’s your knowledge—keep it yours.