Skip to main content

​
Two-Repo Architecture: Agent Behavior vs World Knowledge

​
Goal

Separate agent behavior (replaceable) from world knowledge (permanent) into two repos with strict boundaries.

​
What the User Gets

Without this: agent config and world knowledge are mixed together. Switch agents and you lose your knowledge. Switch knowledge tools and you lose your agent setup. With this: your brain (14,700+ files of people, companies, meetings, ideas) survives any agent swap. Your agent config survives any knowledge tool swap.

​
Implementation

​
The Boundary Test

“Is this about how the agent operates, or is this knowledge about the world?”

​
Quick Decision Tree

​
Agent Repo (operational config)

How the agent works. Identity, configuration, operational state.

​
Brain Repo (world knowledge)

What you know. People, companies, deals, meetings, ideas, media. This is the repo ModusBrain indexes.

​
The Hard Rule

Never write knowledge to the agent repo. If a skill, sub-agent, or cron job needs to create a file about a person, company, deal, meeting, project, or idea, it MUST write to the brain repo, never to the agent repo. The brain is the permanent record. The agent repo is replaceable.

​
Why Two Repos

Independence. You can switch AI agents (OpenClaw -> Hermes -> custom) without losing your knowledge. You can switch knowledge tools (ModusBrain -> something else) without losing your agent setup. Scale. The brain grows large (10,000+ files). The agent repo stays small (< 100 files). Different backup strategies, different sync cadences. Privacy. The brain contains sensitive information (people, deals, personal notes). The agent repo contains operational config. Different access controls. ModusBrain indexes the brain repo. Run modusbrain sync --repo ~/brain/ to keep the search index current. The agent repo is never indexed by ModusBrain.

​
Tricky Spots

  1. Never write knowledge to the agent repo. This is the most common violation. A skill that creates a person page, a cron job that saves meeting notes, a sub-agent that captures an idea — all of these MUST write to the brain repo. If it’s about the world, it goes in the brain.
  2. The brain is the permanent record. When in doubt, ask: “Would this file survive switching to a completely different AI agent?” If yes, it belongs in the brain. Agent configs, skills, cron jobs, and operational state are replaceable. People, companies, ideas, and meetings are not.
  3. Don’t index the agent repo. ModusBrain indexes the brain repo only. Running modusbrain sync against the agent repo pollutes search results with operational config instead of world knowledge.

​
How to Verify

  1. Check file placement. After any skill or cron job creates a file, verify it landed in the correct repo. Person/company/idea/meeting files should be in brain/. Skill/config/cron/state files should be in the agent repo. Any knowledge file in the agent repo is a boundary violation.
  2. Run the boundary test. Pick 5 recently created files and ask: “Would this transfer if I switched AI agents?” and “Would this transfer if I switched to a different person?” If the answers don’t match the file’s location, it’s in the wrong repo.
  3. Verify ModusBrain only indexes brain. Run modusbrain stats and check the indexed paths. None should point to the agent repo directory. If agent config files appear in search results, the sync target is misconfigured.
Part of the ModusBrain Skillpack.