Skip to main content

Facts

Facts are project-scoped key-value pairs that store operational knowledge. They persist across sessions, are categorized for discovery, and support soft-delete with restore.

Creating a fact​

await oprelay.call("upsert_fact", {
  project_key: "myproject",
  category: "infra",
  key: "db.connection",
  value_json: {
    host: "localhost",
    port: 5432,
    database: "oprelay"
  }
});

Reading facts​

// Single fact
const fact = await oprelay.call("get_fact", {
  project_key: "myproject",
  key: "db.connection"
});

// List keys by category
const keys = await oprelay.call("list_fact_keys", {
  project_key: "myproject",
  category: "infra"
});

// List all categories
const cats = await oprelay.call("list_categories", {
  project_key: "myproject"
});

Context retrieval​

The get_context tool returns a bounded snapshot of facts, decisions, and recent runs — scoped by intent and category. This is how agents "get on the bus."

const ctx = await oprelay.call("get_context", {
  project_key: "myproject",
  intent: "I need to set up the CI pipeline",
  include_categories: ["infra", "ci"]
});

Key design patterns​

  • Hierarchical keys: Use dot notation — infra.db.engine, deploy.target.region
  • Categories: Group related facts — infra, product, architecture, deploy
  • Soft delete: forget_fact marks as forgotten; restore_fact brings it back
  • Value is JSON: Store any structured data, not just strings