BeeWeave Turns Agent Sessions Into a Self-Improving Knowledge Loop

GitHub Project URL: https://github.com/ptonlix/beeweave

Here's the thing.

For a while now, I've been using agents like Claude Code, Codex, and OpenClaw to do research, write articles, and organize knowledge.

They are powerful, genuinely powerful. You throw materials at them, they can summarize. You give them a topic, they can draft. You ask them to analyze a repository, they can quickly figure out the structure.

But I kept running into a very annoying problem.

Every time I started a new session, I had to re-explain many things.

What I had researched before, what judgments I had already formed on a certain issue, what clues were left from the last article, which materials were trustworthy, which pitfalls I had already stepped into—the agent often had no idea. We'd have a heated discussion in the last conversation, but once the window closed, the next round felt like meeting for the first time again.

It feels a bit like going to the office every day and having to onboard a highly capable new colleague from scratch.

You can tolerate it for a day or two. Over time, it really becomes unbearable.

So I built BeeWeave.

It's not another chatbot, nor is it just a search box layered on top of Markdown files. BeeWeave is an agent-native knowledge creation workbench, aiming to solve something more specific: connecting material acquisition, content creation, knowledge accumulation, and context reuse into a continuously running closed loop.

Collect, create, accumulate, reuse, then go collect better materials.

Like bees gathering honey, and like weaving scattered threads into a net.

That's where the name BeeWeave comes from.

What I really wanted to solve wasn't memory

When many people see a knowledge base paired with an agent, their first reaction might be Agent Memory.

I was also easily led in that direction at first. But as I worked on it, I increasingly felt that memory alone wasn't enough.

Chat logs are certainly a form of memory. So are bookmarks, web clippings, and dozens of folders stuffed with materials. The problem is, remembering doesn't mean being able to use it.

You bookmark two hundred articles, but when it's time to write, you still start from a blank page. You chat with an agent for over ten hours, but switch to another agent, and the judgments you previously formed can't be carried over. You finish a project, and the experience is scattered across conversations, code comments, meeting notes, and your brain—two months later, you have to do archaeology all over again.

This is what frustrated me.

Knowledge work doesn't end when information is stored. It at least has to go through filtering, creation, verification, accumulation, and recall. Missing any one link, the so-called knowledge base easily becomes a beautifully decorated warehouse.

Everything is there.

You just can't get it out.

What BeeWeave aims to do is not to save everything for the agent, but to establish a knowledge production process. Raw materials can be rough, drafts can be revised repeatedly, but the content that is finally accumulated should be stable, linkable, queryable, and reusable by different agents.

I think this distinction is quite important.

Memory is concerned with "don't forget." BeeWeave is more concerned with "can we do better next time."

Two directories, separating chaos from knowledge

BeeWeave's core structure isn't actually complicated; it's even a bit simple.

The entire workspace is mainly divided into two parts.

project/
├── workbench/
│   ├── inbox/
│   ├── articles/
│   ├── ppt/
│   └── library/
└── vault/
    ├── concepts/
    ├── entities/
    ├── references/
    ├── synthesis/
    ├── projects/
    └── _staging/

workbench/ is the creation workbench.

Web clippings, fleeting ideas, conversation exports, article drafts, presentations, and pending materials all go here first. This area allows chaos and incomplete content, because the real creative process isn't neat and tidy from the start.

vault/ is the compiled knowledge layer.

Only relatively stable content worth reusing later enters here. They are organized into concepts, entities, references, project records, and comprehensive analyses, connected via Markdown and Wikilinks.

Why must it be separated into two layers?

Because I stepped into a very typical pitfall. If all materials go directly into the knowledge base, the knowledge base will eventually be flooded with semi-finished products. A casually jotted note, webpage originals, repeated viewpoints, and genuinely formed judgments get mixed together. Search results look plentiful, but very little can be directly used.

Conversely, if every input is required to be neatly organized from the start, the capture cost becomes absurdly high. Seeing something interesting, you'd first have to think about classification, tags, and archive location—most likely ending up as "I'll organize it when I have time."

And then it never happens...

So BeeWeave accepts a fact: the input phase should be casual enough, while the knowledge layer must be restrained enough.

One side accommodates chaos, the other protects quality.

These two directories are the most fundamental boundary of the entire system.

How it runs

BeeWeave isn't a pipeline that moves files from A to B; it's a cycle.

First, put web pages, notes, PDFs, conversation logs, or project findings into workbench/inbox/. Materials don't need to be refined; just catch them first.

Then let the agent conduct research or creation based on these materials. Long-form article drafts go into workbench/articles/drafts/, while short content, presentations, and materials have their own places. This isn't the endpoint of knowledge, but the place where viewpoints truly collide.

Once an article is published, or a judgment within a project has stabilized, distill the high-signal content into vault/. BeeWeave will organize reusable concepts, facts, relationships, and project experiences into interconnected Markdown pages.

Before starting the next writing or research task, the agent first queries this vault.

Thus, new tasks no longer start from scratch but proceed standing on the context accumulated from the past. Discovering insufficient evidence during queries will expose new problems, guiding the next round of material collection.

This cycle roughly looks like this.

Collect materials
   ↓
Agent participates in research and creation
   ↓
Compile stable knowledge into vault
   ↓
Next task first queries existing knowledge
   ↓
Discover gaps, then collect better materials

Think about it, what truly generates compound interest isn't a single note, but the fact that every work session can leave something for the next one.

An article doesn't just end after publication. It also becomes a knowledge source for subsequent research. A project retrospective doesn't just lie in the archive directory; it can be retrieved by the agent the next time a similar decision is encountered.

This is the data flywheel I wanted.

Not binding to one agent, but letting them share a set of context

Agents have been updating too fast in the past two years.

Today you might mainly use Claude Code, tomorrow Codex might be more handy for a certain capability, and the day after you might delegate some automation to OpenClaw. Switching tools itself isn't a big deal; I even think it's the norm.

The real trouble is that every time you switch tools, knowledge gets locked inside them too.

BeeWeave chooses to keep knowledge in plain Markdown files, turn working methods into Agent Skills, and then connect them through the rules and skill entry points supported by various agents.

Currently, bwe setup supports targets like Claude Code, Codex, Cursor, Gemini, Kiro, Hermes, OpenClaw, Pi, GitHub Copilot CLI, Windsurf, Trae, and the generic AGENTS.md Agent.

The same vault can be queried by different agents. The same set of knowledge organization processes can also be invoked in different environments.

I'm very insistent on this point.

Models will change, agent products will change, and today's popular interaction interfaces will also change. But the articles, concepts, project judgments, and citation relationships you accumulate shouldn't disappear along with a specific product.

Markdown might not look flashy, even a bit old-school. But it's transparent, portable, Git-manageable, and can also be opened directly with Obsidian.

Old-school sometimes is a form of security.

41 Skills, not 41 buttons

BeeWeave 0.5.1 currently has 41 built-in Skills.

Seeing this number, some might think, oh no, another complex system requiring memorizing commands.

I totally understand this feeling. I myself don't like reading a hundred-page manual just to use a tool. BeeWeave's design direction isn't for people to remember 41 commands, but for the agent to invoke the appropriate workflow based on natural language tasks.

The three core actions are actually very easy to understand.

/beeweave-ingest workbench/inbox
/beeweave-query What do I already know about Agent Context Engineering
/beeweave-update

beeweave-ingest is responsible for distilling input materials into reusable knowledge.

beeweave-query is responsible for retrieving relevant context from existing knowledge before starting work.

beeweave-update is responsible for syncing back newly formed stable experiences from the project.

Around these three actions, BeeWeave also provides Skills for web capture, long-form writing, social content adaptation, article publishing, knowledge synthesis, deduplication, cross-linking, graph analysis, status checks, historical session import, and context packaging.

The article you are reading is a real case study

After talking so much about the workflow, the most direct way is to use a live example.

That's this article you are reading right now.

I didn't start from a blank dialog box, nor did I copy all of BeeWeave's project materials and writing requirements back to the agent. I first placed a previously published GoHumanLoop article into workbench/articles/published/, using it as a style reference for this writing task.

Then I only proposed one task: based on the writing style of that article, write an article introducing the BeeWeave open-source project, and place the draft into workbench/articles/drafts/.

After receiving the task, the agent first read that GoHumanLoop article and extracted its progression method. Project introduction, problem scenario, implementation mechanism, installation and running, then back to usage effects and boundaries.

Next, it didn't just write based on my one-sentence description; it checked BeeWeave's project description, the locally installed version, CLI commands, built-in Skills, supported agents, and the GitHub remote repository. After confirming the facts, it reorganized this information into the current article.

I think this step is particularly critical.

The reference article provided "how I'm used to telling a story," while the project materials provided "what exactly needs to be told this time." One is responsible for style and structure, the other for facts, both staying in the workspace without me needing to manually assemble them into a huge prompt each time.

After writing, the draft was saved as a Markdown file, entered workbench/articles/drafts/, and underwent a round of checks for forbidden words, structure, content, and a human touch.

Then, after reading the draft, I added one piece of feedback.

"A typical case study of using BeeWeave is the very content you are writing."

So the agent returned to the same draft, kept the previous structure, and added the section you are reading now.

Can you believe it???

An article introducing BeeWeave is completing itself using BeeWeave's workflow.

Right now, it's still just a draft. Once I confirm publication, it will enter workbench/articles/published/. The published article can then continue to be ingested back into the vault. The stable content within it about agent-native knowledge creation workbenches, the dual-layer structure of workbench and vault, and cross-agent context reuse will become knowledge that can be directly invoked for the next writing and research task.

Reusing writing styles from old articles, generating new drafts based on project facts, continuing to modify based on human feedback, and after publication, depositing the results back into the knowledge base.

Having run this entire loop, what BeeWeave aims to do is no longer just an architecture diagram.

It really happened within this article.

A bit of a matryoshka doll.

But I quite like this matryoshka, because the system has truly started using its own output to improve the next round of input.

From installation to the first query

BeeWeave has been published on PyPI, requiring Python 3.9 or higher. The fastest installation method is just two steps.

pip install beeweave
bwe setup

Run bwe setup in the directory you intend to use as your knowledge workspace. It will create vault/ and workbench/, write the BeeWeave configuration, and ask for which agents you want to install Skills and project rules.

After installation, you can first check the current information.

bwe info

If you already have some materials on hand, put them into workbench/inbox/, then call ingest in the agent.

/beeweave-ingest workbench/inbox

Once there is content in the vault, you can start querying.

/beeweave-query What viewpoints have I formed on Human-in-the-loop

If you have separate knowledge bases for work and personal use, you can also create named profiles, using @work or @research to route a single request to the specified workspace, without needing to change the default configuration back and forth.

The entire process has no database service to maintain, and no cloud storage you must purchase. The core asset is just a set of local Markdown files.

Of course, just because I say it's easy doesn't mean the knowledge base will grow automatically.

When you first start using it, classifications might be inappropriate, tags might be messy, and pages distilled by the agent require human judgment. The more materials you have, the more important deduplication, linking, and quality control become. BeeWeave provides processes like lint, dedup, cross-linker, stage-commit, and graph analyse, but it won't decide for you what knowledge is truly important.

I must be honest about this.

Tools can lower maintenance costs, but they cannot replace judgment.

Who it suits, and who it doesn't

If you just want to chat temporarily with a model and leave after the chat, BeeWeave might be too heavy. Creating two directories and maintaining a vault would actually increase the burden.

If you're used to dumping all materials into a search product and are satisfied as long as you can search the original text, you might not need BeeWeave either. It emphasizes distillation and reuse, not mere hoarding.

But if you use multiple agents long-term, continuously write articles, do research, develop products, or advance projects, it will be more valuable.

Especially the following type of person should easily understand why I built it.

You completed research in Claude Code but want to bring the context to Codex. You've written dozens of articles but find yourself repeatedly looking up materials for each new topic. You have a large Obsidian vault, but the agent doesn't know where to start reading. You've accumulated a lot of experience after finishing projects, but can't recall it the next time you really need it.

I myself am the sum of all these problems..

So BeeWeave didn't start from a grand theory of knowledge management. It grew out of repeated explanations, repeated searches, and repeated forgetting.

Solve my own pain points first, then see if it can help others with similar struggles.

Why I'm open-sourcing it now

Frankly speaking, BeeWeave is still very early.

It's currently in the Beta stage, and many processes still have room for further refinement. Different agents support Skills in slightly different ways, and the retrieval quality of large-scale vaults is also affected by content structure, tags, and optional semantic search configurations. The more complex the workflow, the more the user needs to understand the boundary between workbench/ and vault/.

But I still decided to open-source it now.

Because knowledge work shouldn't be designed around just one model, one platform, or one note-taking habit. The ways people use agents vary greatly; some write, some develop, some do academic research, and some manage project knowledge for a company.

Trying to perfect the process behind closed doors is basically impossible.

BeeWeave is more like a base that can be experimented on together. You can contribute better ingest strategies, new agent history importers, vault quality checks, graph analysis, or a sufficiently focused Skill for a real work scenario.

The repository uses the MIT License. The code, Skills, bootstrap templates, and browser capture extension are all on GitHub.

If you're willing to try it, you're welcome to actually install BeeWeave and run a round with your own materials. Only by entering the real scene of writing, research, and projects will its problems and value be exposed.

If you find this direction somewhat interesting, welcome to give a Star on GitHub. If you encounter bugs, awkward processes, or confusing documentation, feel free to directly submit an Issue. If you're willing to contribute code, documentation, new agent adaptations, or a genuinely useful Skill, you're even more welcome to submit a PR.

Usage, Stars, Issues, PRs—all are welcome.

An open-source project isn't something the author thinks up alone in a room; it grows out of real usage and repeated feedback. Every problem and improvement you leave behind might help the next person using BeeWeave avoid a pitfall.

I dare not say this is already the answer to knowledge management in the age of agents.

Honestly, we are still far from it.

But I always firmly believe one thing. What truly sets people apart in the future isn't just how powerful a model you use, but also whether you have turned what you left behind from every work session into the starting point for the next one.

Models are getting stronger every day.

The context that belongs to you should start growing too.

GitHub Project URL

https://github.com/ptonlix/beeweave