Knowledge Base

The knowledge base is a git-versioned collection of project context that all agents share. It enables consistent decision-making across your team.

Overview

When you create a team, Operum initializes a .operum/knowledge/ directory in your repository. This directory contains structured files that agents read for project context before starting work.

Git-Versioned: The knowledge base lives in your repo and is tracked by git. Changes are automatically committed, giving you full version history.

Directory Structure

.operum/knowledge/
├── project.yaml           # Project name, description, tech stack
├── goals.yaml             # Strategic and near-term goals
├── decisions.md           # Architectural decisions log
├── team-log.md            # Agent activity log (auto-updated)
├── workflow.md            # Pipeline stage definitions
└── artifacts/
    └── links.yaml         # Important URLs and references

Core Files

project.yaml

Defines your project identity and technical context. Agents reference this for branding, tech stack awareness, and integration details.

name: My SaaS App
tagline: AI-powered analytics platform
description: >
  A real-time analytics dashboard built with
  Next.js and PostgreSQL.

repo:
  owner: myorg
  name: my-saas-app
  url: https://github.com/myorg/my-saas-app

version: 1.2.0
stage: beta

tech_stack:
  frontend: Next.js 14 + TypeScript
  backend: Node.js + Prisma
  database: PostgreSQL
  hosting: Vercel + Railway

integrations:
  current:
    - GitHub (Issues, PRs)
    - Telegram (Notifications)
  planned:
    - Slack

goals.yaml

Tracks project goals by timeframe. Agents use this to prioritize work and understand the product roadmap.

immediate:
  - goal: Fix authentication bug
    status: in-progress
    priority: high

  - goal: Add dark mode
    status: not-started
    priority: medium

short_term:
  - goal: Launch beta to 100 users
    milestones:
      - Core features complete
      - Onboarding flow tested
      - Documentation ready

long_term:
  - Enterprise SSO integration
  - Mobile app
  - API marketplace

links.yaml

Central reference for important project URLs. Located in artifacts/links.yaml.

websites:
  landing: https://myapp.com
  docs: https://docs.myapp.com
  status: https://status.myapp.com

infrastructure:
  database: https://railway.app/project/xxx
  hosting: https://vercel.com/myorg/my-app
  monitoring: https://app.posthog.com

documentation:
  api_docs: docs/api.md
  architecture: docs/architecture.md

decisions.md

A running log of architectural and technical decisions. Agents can record decisions here, and all agents can reference them for context.

## 2026-02-01 - Use PostgreSQL over MongoDB

**Context:** Need a database for user analytics data.
**Decision:** PostgreSQL with Prisma ORM.
**Rationale:** Strong typing, ACID compliance, better
for relational data patterns in our analytics queries.

team-log.md

Automatically maintained by agents as they work. Each agent appends entries when completing tasks, providing a timeline of team activity.

## 2026-02-05 14:30 - Engineer
- Implemented dark mode toggle
- PR #42 created for issue #38

## 2026-02-05 14:35 - Tester
- PR #42 passed QA review
- All tests passing, no regressions
Auto-Updated: You don't need to edit team-log.md manually. Agents append to it as part of their workflow.

Editing the Knowledge Base

You can edit knowledge base files in two ways:

  1. In-App Editor - Navigate to the Knowledge page in Operum to edit files with a visual interface
  2. Direct File Edit - Edit the YAML/Markdown files in .operum/knowledge/ with any text editor

Changes are synced to git automatically. If you edit files directly, the app will detect changes on next refresh.

Knowledge Sync

The knowledge base supports git-based sync:

  • Pull - Fetch knowledge updates from the remote repository
  • Push - Push local knowledge changes to the remote
  • Conflict Resolution - If conflicts occur, Operum provides a resolution UI

Onboarding

When you set up a new team, the PM agent runs an onboarding conversation that populates the knowledge base with your project details. This includes:

  1. Project name, description, and tech stack
  2. Repository and website URLs
  3. Current goals and priorities
  4. Team conventions and coding standards

You can always edit these values later through the Knowledge page.

Best Practices

  • Keep goals current - Update goals.yaml when priorities shift so agents work on the right things
  • Record decisions - Log important technical decisions so agents maintain consistency
  • Add useful links - Include documentation URLs, dashboards, and resources agents might need
  • Review the activity log - Check team-log.md periodically to understand agent workflow patterns
  • Commit regularly - Keep the knowledge base in sync with your repo for version history