DEV Community: Mischa

A Seond Brain For Your Agents

Mischa — Wed, 29 Apr 2026 09:02:43 +0000

One of my agents was about to start a web search for design token naming conventions. The task was in my design system project, and watching the session live, I already knew what it would find: a mix of opinions, half-applicable patterns, and general best practices.

The thing was, this question had already been settled in another active session. Different agent, same project, working on a related part of the system. There were examples and a short doc that explained why I chose what I chose.

So I pressed ESC.

One pointer to my second brain gave it the right entry to read. Within seconds it had the same context that had taken hours to build up earlier.

The lost time was not the real issue. The real risk was different: the agent would have found something. Maybe close to the earlier decision, maybe not. Either way, it would have used what it found and silently overwritten decisions made earlier in another session, while the other agent kept building on the original ones. Two agents working on the same project, drifting apart, with no warning until much later.

Agents do forget. Context windows fill up, summarizations drop the details, and every new session starts blank. You cannot fix that inside the model. You fix it outside, with a memory that survives the next reset.

The core problem

Agents are stateless. Every new session starts at zero, with no recollection of what was decided yesterday or in the parallel branch.

This is the part that scales the wrong way. A solo agent on a small task barely notices it. The moment you run multiple sessions across multiple worktrees, the gaps multiply.

Two reactions to this are common, and both are wrong.

The first is to dump everything into the prompt: every doc, every decision, every past chat. This will bloat the context and the quality might decrease because of context rot.

The second is to hold nothing back at all. No persistence, no notes, no shared state. The agent re-researches the same questions, reopens settled debates, and quietly contradicts decisions made last week.

What you actually need is something in between: a structured memory that lives outside the context.

From Notion to agent memory

If you have ever maintained a personal knowledge system, this part will feel familiar.

For years, my own second brain lived in Notion. It was working infrastructure: documenting learnings, tracking decisions, managing tasks for my design system work. The setup did its job.

Then agents entered my workflow, and Notion stopped being part of it.

The problem was not that Notion is bad. It is good at what it does. The problem was that it is built for humans: pages are long, context-rich, and formatted for reading and skimming. I know there are MCP servers that can bridge Notion into an agent session, but each server you connect registers its tool definitions in the context, whether those tools get called or not. Every additional server bloats the agent’s base context before any actual work has started, and spending that budget on personal knowledge management is hard to justify when this context could be used for something you actually use during development.

The simpler alternative was already on my disk: a folder of markdown files in a git repo. Versioned, diffable, shareable, and free of tool overhead. The format works for the agent, the storage works for me, and the whole thing can be cloned into another machine or shared with a teammate the same way any other repo is.

Once a todo or a project is finished, the file gets deleted. Keeping the second brain small is part of the point, and git history is there if anything ever needs to be looked at again.

The underlying need was the same in both worlds: an externalized memory the new session can read on its own. Only the reader had changed.

The second brain I built in Notion was for me. This one is for my agents.

Setting it up did not require starting from scratch. The first version came together in one session with my agent. I gave it the structure and the naming conventions, it scaffolded the files, and we refined the rest as we went. None of it was perfect on day one. None of it had to be.

What it actually is

Disclaimer: The setup described in my article runs on Claude Code, because that is what I use. The structure itself is tool-agnostic: any agent that reads project files benefits from the same three layers, the same typed files, and the same Why pattern. What changes between tools is only the entry file the agent looks for by default.

On disk, the second brain is a folder of markdown files. The structure on top of those files is what makes them useful as agent memory, and it splits into three layers, each with a clear job.

The global layer lives in my ~/.claude/CLAUDE.md and contains my identity, tech stack and working style. It loads into every session, every project, and stays the same across them.

The project index lives at memory/MEMORY.md. Hard-capped at 200 lines on purpose. It does not contain knowledge itself. The project index is a list of pointers, one line per entry, each linking to the actual file. The agent reads the index first to decide what is relevant for the current task, then opens only the files that matter. Retrieval is judgment-driven, not keyword-based, and the index stays small enough to fit in context without effort.

The individual files live in the same memory/ folder, named {type}-{slug}.md. There are four types, each with a different lifecycle.

feedback: corrections and validated patterns ("never do X, here is why")
project: in-flight work, decisions, bugs, todos, initiative status
reference: where to find things in external systems, like a Figma file, or a docs path
user: role, expertise, communication preferences

Every file follows the same shape:

Rule or fact
Why
How to apply

The Why is the load-bearing part. A rule without context is something the agent follows. A rule with the reasoning attached is something the agent can apply in edge cases that nobody anticipated.

How to build it

Here is what the structure looks like for a single project:

~/.claude/
├── CLAUDE.md
└── projects/
    └── my-wonderful-project/
        └── memory/
            ├── MEMORY.md
            ├── user-profile.md
            ├── feedback-no-hardcoded-tokens.md
            ├── project-token-rename.md
            └── reference-jira-board.md

The MEMORY.md index is the table of contents the agent reads first. It groups entries by type and links each one to its file:

## User
- [User Profile](user-profile.md): UX engineer leading the design system team

## Feedback
- [No hardcoded design values](feedback-no-hardcoded-tokens.md): a hardcoded color broke dark mode last quarter

## Project
- [Token rename](project-token-rename.md): aligning Figma variables with CSS custom properties, deadline before Q3 launch

## Reference
- [Jira board](reference-jira-board.md): design system tickets in project "DSY"

Each individual file uses YAML frontmatter for discoverability and a body shaped as rule or fact, then Why, then How to apply:

---
name: No hardcoded design values in components
description: Components must reference semantic tokens, not raw values
type: feedback
---

Never hardcode colors, spacings, or font sizes in component styles. Always reference semantic tokens.
**Why:** Last quarter, a hardcoded `#1E1E1E` slipped past review and broke dark mode for one component. Tokens turn a global update into a one-line edit. Raw values force you to grep across the codebase every time.
**How to apply:** Components only consume CSS custom properties from the token layer (`--color-surface-primary`, `--space-md`, etc.). The linter blocks hex values, raw px units, and named CSS colors in component files.

That is the entire shape, repeated for every entry.

Talking to the second brain

Two kinds of prompts cover most interactions. The first one loads context:

Before you start, check the second brain. There is a decision on design token naming conventions with examples and a short doc explaining the trade-offs.

The second one saves context:

Save this to the second brain as feedback type. Components never hardcode colors or spacings, only semantic tokens. Last quarter a hardcoded color slipped past review and broke dark mode.

The agent reads MEMORY.md, decides which files to open, and either uses what it finds or creates new files and updates the index, following the same shape.

Two real cases

For my CLI project Kigumi, work happens in parallel worktrees: one for the CLI itself, others for the wrapper templates for multiple frameworks. When a CLI refactor unblocks a wrapper, the wrapper session does not have to stop while the CLI gets fixed. The new requirement gets saved as a project entry in the second brain. The CLI session picks it up the next time it reads MEMORY.md for context. Once the todo is checked off, every other session sees the same status the next time it loads the index.

The same pattern works for design. Reading design tokens out of Figma and comparing them against the CSS custom properties in code, I spotted naming inconsistencies and a few off-by-one references. The current task did not need that fix, so the issue went into a project entry as a list of concrete todos. Two weeks later it was still there, with all the context attached.

What you will have to iterate

The first version of the second brain will be wrong in places. The early rules will be too broad. A How to apply section that seemed clear will turn out to be useless when an actual edge case shows up. A project file will grow until it stops being one entry and starts being three.

That is not a failure mode. It is how the system improves. Each time a rule misfires, the file gets sharper. Each time a project file gets too big, it gets split. The feedback type accumulates corrections over months, and what was once a vague guideline becomes a specific pattern with examples and counterexamples.

The second brain gets better because you use it, not despite it.

Conclusion

The ESC moment from the opening is the small version of a much larger pattern. Without somewhere to write things down, every agent starts blank, every decision is at risk of being made twice, and every session is one reset away from losing its context.

A second brain is not a productivity hack. It is the precondition for agentic workflows to hold together over weeks of work, across worktrees, and between agents that need to share what they know.

Kigumi: Same components, any stack

Mischa — Tue, 24 Mar 2026 12:33:32 +0000

What if the same button component worked in React, Vue, Angular, and Svelte without changing a single line? Most UI libraries and tools don’t let you do that. They’re tied to one framework, and the moment you switch, you start over.

Kigumi takes a different approach. It’s built on Web Awesome, a library of 70+ production-ready web components powered by Lit. These are real HTML custom elements that the browser understands natively. Web Awesome also ships with an excellent design token system and layout CSS classes, built entirely on CSS custom properties, giving you full control over colors, spacing, typography, and more.

The problem is that raw web components still have friction inside frameworks. React 18 requires manual event listener setup for custom elements. React 19 improved this significantly, but depending on the component library, you may still run into edge cases with event naming and TypeScript support. Vue needs shim types and extra work for proper slot and event handling. That’s where Kigumi comes in.

Getting started with Kigumi

Kigumi is a CLI that generates idiomatic framework wrappers around Web Awesome components. It takes Web Awesome’s excellent component library and token system and makes them easy to use, customize, and share across your projects.

You don’t need to install anything globally. Just run:

# Initialize a new Kigumi project
npx kigumi init

# Display all available CLI commands
npx kigumi --help

Kigumi detects your framework, your TypeScript setup, and your package manager. It configures the CSS layers, registers the web components, and generates the type declarations your editor needs. Just follow the instructions of the CLI.

Then you add components as you need them:

npx kigumi add button input dialog

Each command generates a proper wrapper for your framework. A React project gets a .tsx file with correct prop types, forwarded refs, and event listeners with proper cleanup. A Vue project gets a .vue single-file component. TypeScript types and accessibility features are included out of the box.

Once generated, the code lives in your repository. You own it. You can edit it, extend it, or strip out the parts you don’t need.

React is fully supported today. Vue support is available and getting closer to full parity. Angular and Svelte are on the roadmap, along with additional framework targets.

CSS that works with the platform, not against it

Kigumi’s theming is built on two native CSS features: custom properties and cascade layers.

Custom properties are how you theme your components. Web Awesome exposes its entire design language as CSS variables. You override them in a single file, and every component picks up the change. No JavaScript theme providers. No context wrappers. Just CSS doing what CSS was designed to do.

/* theme.css */
:root {
  --wa-color-primary-600: #4f46e5;
  --wa-font-sans: 'Inter', system-ui, sans-serif;
  --wa-border-radius-medium: 6px;
}

Cascade layers solve the specificity wars. Kigumi wraps Web Awesome’s base styles in a @layer, so your overrides always win without needing !important. The generated layers.css handles the ordering automatically. Base styles sit below your theme. You don't have to think about it.

/* layers.css */
@import "@awesome.me/webawesome/dist/styles/webawesome.css" layer(base);
@import "./theme.css" layer(theme);

The theme.css file is yours. Kigumi creates it during init and never overwrites it.

Side note: Kigumi is fully compatible with Tailwind CSS. You can use utility classes alongside your components. Depending on your Tailwind configuration, you may need to rename Kigumi’s base layer to avoid a conflict with Tailwind's own base layer. But we're excited about what CSS custom properties and cascade layers enable natively, so that's where our focus is.

Kigumi Studio: design your theme visually

Not everyone wants to write CSS variables by hand. Kigumi Studio is a visual theme editor that lets you customize colors, typography, spacing, and more in real time. You see your changes reflected instantly on live component previews.

When you’re happy with the result, export the generated CSS into your theme.css file. You can also publish your theme to a registry so your entire team, or the community, can use it.

The registry: share components and themes across teams

Beyond the built-in component set, Kigumi has a community registry system. Any team can publish their own set of components and themes, and anyone else can install from it.

Creating a registry takes one command:

npx kigumi registry init

This scaffolds a registry.json that describes your components and themes. Add your files, push to GitHub, and your registry is live.

Consuming a registry is just as simple. Add it once, then install from it by name:

# Add the registry source
npx kigumi registry connect https://github.com/your-org/ui-registry --name design-system

# Install components from it
npx kigumi add card --from design-system
npx kigumi add hero-section --from design-system

Kigumi fetches the files from GitHub, resolves dependencies automatically, and tracks the source of each component in your project config. If your card component depends on a badge, Kigumi installs that too.

Combined with Kigumi Studio, the workflow becomes powerful: design a theme visually, export it, add it to your registry, and every project that connects to your registry gets access to it.

Built for AI agents

Kigumi ships with a set of agent skills for tools like Claude Code and Cursor. These aren’t just documentation. They teach your AI assistant how to build complete features using Kigumi components.

npx skills add https://kigumi.style/skills/kigumi

The skills cover individual component conversion (Web Awesome HTML to React or Vue), but they go further than that. There are composition skills that let your agent build entire features: forms with validation and error handling, page layouts using Web Awesome’s utility classes, modals and drawers with correct state patterns, or data tables with loading and empty states. The skills are combinable, so asking your agent for “a form inside a dialog” just works.

Theme customization is covered too. Your agent can work directly with the design token system to adjust colors, typography, spacing, and dark mode.

We’re also working on something we’re particularly excited about: a Pencil file that brings design into the AI workflow. The idea is to let agents work across both design and engineering, so that going from a design concept to a fully implemented, themed component becomes a single continuous process rather than a handoff between tools.

What’s next

React support is stable and covers 73 components today. Vue is in beta and getting closer to full parity. Angular and Svelte wrappers are in early development, with more framework targets to follow.

On top of that, the AI integration is a big focus. We want agents to understand the full Kigumi ecosystem: components, themes, registries, and design. The Pencil file is a first step toward that vision.

The beauty of building on Web Components is that the underlying wa-* elements don't change between frameworks. When Angular support ships, running npx kigumi add button in an Angular project will produce the same quality of output that React and Vue projects already get.

Same components. Any stack. Whether you type the commands yourself or let an agent do it.

Get started at kigumi.style or run npx kigumi init in your project.