Designing an Agent-Assisted Personal Knowledge System

I used to run both my site and my knowledge management system from Notion. That was convenient for publishing, but had several downsides:

• No version control.
• Automation is harder through Notion API
• And most importantly: notes, links, drafts, and ideas lived too far away from the tools I use to think and build.

Moreover, a crucial new axis has emerged in the last two years: AI Agents. A lack of automation was not really important for me in the past. It was expensive to create and maintain while creating little value. With AI Agents this is no longer the case.

The replacement is then driven by these motivations:

• Have the lowest friction for capture possible, so it encourages me.
• Make it easy for AI Agents to interact with the knowledge base while allowing me to control the AI agents output.
• Being able to link my knowledge base to the original authored content in my website.

[!info] I am taking inspiration for the Karpathy’s LLM Wiki and Edu Ferro article on managing their Obsidian vault.

The new system consist on:

• An Obsidian Vault version controlled in a private repo.
• A new knowledge management system that fits my needs.
• A collection of scripts for validation and automation.
• An upgraded website using Astro and plain markdown.

The Tools

Obsidian Vault

I have been a Notion fan since forever. I will still use notion for other use cases. But for my knowledge management system, Obsidian is the best choice at the moment.

The new system needs to be accessible in version control and by agents. With Obsidian, I can have my vault in a repo. It is just a collection of folders and Markdown files. So it is the obvious choice to put scripts and agents on top.

I also been finding their web clipper super powerful. It is allowing me to add layers on top of just “bookmarking”.

New Astro Site

My website used to be run from Notion using the Next Notion Started Kit. It was convenient because I was used to notion and it provided an easy way to manage the content and layout of my website.

Now that the decision to move away from notion was clear, I needed another lightweight static website tool that allows for low maintenance publishing. My requirements were:

1. Has to be able to publish easily in vercel.
2. Can author markdown content easily.

Astro checked both things. The rest for me are nice extras which I am still exploring

Scripts

As the website and vault are now two separate repos, I needed some way of automating the process of publishing content.

The collection of scripts have to be very dumb at the first stage. They have two main roles:

1. Move markdown files between repos following certain business rules. For example, published: true is set in the file properties.
2. Validate file properties, tags, and links.

In the future the scripts might evolve to do more things. In particular, helping AI agents to do work. But I am intentionally going one step at a time

AI Agents

Agents help with the intermediate processes in the knowledge vault system: moving the quick captured notes into structured and linked useful information. They do not own the final output of my published content.

Agents are useful when the task is structured and reviewable.

I am still experimenting in which exact collection of Skills and agent harnesses are the best for this job.

The Knowledge Management System

I was investigating several options for the system to follow. I investigated:

• PARA
• Zettelkasten
• Digital Garden

None of them really reasonated with me fully. I wanted a system that was easier for me to follow. In this particular area of knowledge management, I think it is better that the system adapts to you instead of you adapting to the system.

I refined several ideas with the help of Codex, and ended up in a system that borrows some concepts for each of them.

The system has 5 working areas:

• inbox/ : everything goes here as a low friction capture dump
• library/: keeps captured raw source material.
• garden/: keeps distilled linked notes.
• studio/: keeps original authored content intended for publication or as refined projects.
• maps/: keeps durable entrypoints into broad topics.

The high level structure is fixed so entrypoints to each concept are clear. But for each of them, there could be more nesting levels as I see fit.

The Inbox

The inbox is the only place where capture is allowed to be messy.

That matters because the failure of most personal knowledge systems is not lack of structure. It is too much structure at the point of capture. If saving a link requires deciding the perfect folder, topic, tags, and future use, I will avoid saving it or I will save it somewhere inconsistent.

So the inbox has a simple contract:

• Capture first
• Preserve source context
• Add enough metadata for cleanup
• Defer structure until review

For web links, the default capture is using Obsidian’s Web Clipper tool . I am using their default template for clipped content with an extra though property to capture my thoughts or rationale (if there was any) associated with that link.

The cleanup loop turns inbox items into one or more durable artifacts in the other folders. Inbox notes are never final, they are the raw material of the rest of the system.

Library

The library contains the raw source content from my captures. Having it inside my vault is nice to avoid dead links or content drift in the future. Also, obsidian provides a nice tooling of note linking, so I can trace back other notes to the sources in the library easily.

Garden

This borrows the idea of the digital garden and a bit of Zettelkasten notes. Here lives unstructured and atomic thoughts that can be linked between each other or with other elements of the system.

Some use cases could include:

• Reading an article spawned and idea to revisit later
• Conversation with a colleague about clean architecture gave me insights about something specific
• Note down into words realizations about my career goals.

The garden provides a intermediate layer between the library, my original ideas, and the fully fledge ideas in the studio. Similar to the inbox, it is almost like a “brain dump”. What makes it different to the inbox is that:

1. It only contains my curated thoughts or notes, not others people full articles or quotes.
2. It has already structure. While the inbox is loose by design, notes in the garden should already being placed with rich linking and metadata.

Studio

This borrows some concepts from PARA framework, in particular Projects and Resources. Content in studio is longer, curated, and edited. Think of it like the “editorial” part of my knowledge base.

The idea comes directly from the need of publishing in my website while maintaining the knowledge vault as a source of truth. However, while all content in the site will be in the studio, not all content of the studio needs to be in the site.

The studio could contain original blog posts, source materials for talks, online courses notes, my resume, project oriented information… For example, I plan to migrate some of the knowledge stored in notion that I had from my Bachelors and MSc degrees into the studio.

Not all my personal projects should be in the studio. Things that need to be shared and collaborate with other people I would still store it in Notion. It is also a good idea in general that the information of the projects live close to the projects themselves: github repos for development, google drive and excel for personal and profesional documentation…

Maps

The powerful aspect of a good knowledge management system is the ability to link concepts and areas together. This is where maps is useful.

The idea is to use maps as a file entrypoint for areas that links Garden, Library, and Studio files together. So it serves as the first step to navigate the knowledge base.

I am still experimenting with this category. Maintaining it by hand is a big pain. Obsidian already gives a good linking experience. But I think it could be interesting if I manage that AI agents maintain this automatically as it will create obvious structure and nodes in the knowledge graph.

From Captures To Original Work

The goal is not to collect more links. The goal is to make it easier to develop original thinking.

A useful cleanup session should answer:

• What is the source saying?
• What do I agree or disagree with?
• What existing notes does this connect to?
• Does this change one of my maps?
• Is there a public article, snippet, talk, or project note hiding here?

The publishing path is deliberately one-way:

vault/studio/*.md -> website/src/content/*/*.md -> astro build

The website never reads the private vault directly. It receives only explicit public exports.

Future Work

The first version starts boring on purpose: Markdown, Obsidian-compatible folders, Python scripts, Astro, and simple search.

Future improvements should be added only when the simple workflow starts to hurt:

• Link and metadata validation before export
• Privacy checks for public drafts
• Automated map health reports
• Source freshness checks
• Duplicate-note detection
• Local semantic search
• Graph visualization
• MCP access for agent search
• Generated reading queues
• Automatic “what changed in my thinking?” summaries

Tools like Graphify, QMD, engraph, or other graph/search systems are candidates for later. They should improve the existing vault rather than replace the Markdown source of truth.