Project Knowledge

A git-versioned collection of project context shared across all agents. The longer you use Operum, the smarter it gets.

When you create a team, Operum initializes a .operum/knowledge/ directory in your repository. Agents read it for project context before every task, and it travels with your repo like any other file.

What a new team starts with

Three files, created for you when the team is set up:

  • project.toml — your project's name, description, website and repository
  • goals.toml — strategic and near-term goals
  • artifacts/links.toml — URLs and references worth keeping to hand

They start almost empty. The PM agent's onboarding conversation fills them in, and they grow as you work — that is the whole idea: the longer you use Operum, the more context your agents have.

A Quick Start team also arrives with a few starter Markdown files for decisions, security notes and release process, so there is something to write into rather than a blank directory.

TOML, not YAML. These files used to be .yaml. If you have an older project, Operum migrates them to .toml for you the first time it reads them — you don't need to do anything, and older guides naming project.yaml or goals.yaml are describing the previous format.

Two files Operum maintains for you

  • index.toml — a generated index of everything in the knowledge base, so an agent can find the right document without reading all of them. Regenerated on every sync.
  • repo-map.toml — a generated map of your source tree. This one is not committed; it is rebuilt locally as your code changes.

Don't hand-edit either. Both are rebuilt from scratch, so edits are overwritten. Change the documents they describe instead.

Editing, and what happens to your changes

You can edit these files in your own editor like any other file in your repo. Inside Operum, the Project Knowledge page has an Edit with PM action: you describe the change you want and the PM agent makes it.

Changes are not committed silently. The knowledge base is a protected area, so agents can't quietly rewrite it underneath you. Changes go through a reviewed pull request like any other change to your repository — you see what moved, and you approve it. That is also why you get real version history: every edit is an ordinary commit with an author and a diff.

Keeping it in sync

Project Knowledge lives in git, so it syncs the way your code does — pull to pick up changes made elsewhere, push to share yours. If the same file changed in two places, Operum surfaces the conflict for you to resolve rather than silently picking a side.

Onboarding

When you set up a new team, the PM agent runs an onboarding conversation that populates Project Knowledge with your project details: name, description, tech stack, repository and website URLs, current goals and priorities, and your team's conventions. You can change any of it later.

Best practices

  • Keep goals current — update goals.toml when priorities shift; it is the file agents lean on most when deciding what matters
  • Record decisions as you make them — the reasoning behind a choice is the part that gets lost, and it is what stops an agent re-litigating it later
  • Add useful links — documentation, dashboards, design files
  • Let it grow — a thin knowledge base is normal on day one; it earns its value over weeks, not minutes

What's Next?