Memory Tools

Tools for reading and writing OpRelay's operational memory — facts, decisions, and context.

---

upsert_fact

Create or update a fact. Upserts on (project_key, category, key).

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
category	string	✓	Category for grouping (e.g. infra, ci, deploy)
key	string	✓	Fact key within the category
value_json	any	✓	JSON value — any structured data (also accepted as value)
confidence	number/string		Epistemic confidence: assumed (0.3), observed (0.6), inferred (0.7), confirmed (1.0), or a float 0–1
tags	string[]		Searchable tags (max 32)
source	string		Source identifier (default: "manual")
agent_id	UUID		Agent that created/updated the fact
run_id	UUID		Run that produced this fact

await oprelay.call("upsert_fact", {
  project_key: "myproject",
  category: "infra",
  key: "deploy.target",
  value_json: { provider: "oci", region: "us-ashburn-1" },
  confidence: "confirmed",
  tags: ["deploy", "production"]
});

---

get_fact

Retrieve a single fact by category and key.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
key	string	✓	Fact key
category	string		Category (narrows lookup)

const fact = await oprelay.call("get_fact", {
  project_key: "myproject",
  category: "infra",
  key: "deploy.target"
});

---

forget_fact

Soft-delete a fact. Recoverable with restore_fact.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
key	string	✓	Fact key to forget
category	string		Category (narrows lookup)

---

restore_fact

Restore a soft-deleted fact.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
key	string	✓	Fact key to restore
category	string		Category (narrows lookup)

---

get_context

Bounded context retrieval. Returns facts, decisions, and recent runs scoped to intent and categories. This is how agents orient on session start.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
intent	string		starting_task, reviewing, supervising, remediating, or general
task_id	UUID		Scope context to a specific task
ticket_id	string		Scope context to a ticket
include_categories	string[]		Restrict facts to these categories (max 32)
exclude_categories	string[]		Exclude facts from these categories
max_facts	number		Fact limit (default: 5, max: 200)
max_decisions	number		Decision limit (default: 3, max: 200)
max_runs	number		Run limit (default: 3, max: 200)
include_fact_meta	boolean		Include fact metadata in response (default: false)
include_run_meta	boolean		Include run metadata in response (default: false)
agent	string		Requesting agent name (for context scoring)

const ctx = await oprelay.call("get_context", {
  project_key: "myproject",
  intent: "starting_task",
  include_categories: ["infra", "ci", "deploy"],
  max_facts: 10,
  max_decisions: 5
});

---

clear_context

Delete all facts and decisions for a project. Irreversible.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier

---

list_categories

List all fact categories used in a project.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier

Returns an array of category strings.

const { categories } = await oprelay.call("list_categories", {
  project_key: "myproject"
});
// ["ci", "deploy", "infra", "services"]

---

list_fact_keys

Browse fact keys, optionally filtered by category or key pattern.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
category	string		Filter to a single category
pattern	string		Substring or glob pattern to match key

const { keys } = await oprelay.call("list_fact_keys", {
  project_key: "myproject",
  category: "infra"
});
// ["deploy.target", "db.host", "db.port"]

---

list_projects

List all project keys visible to the caller.

No parameters required.

const { projects } = await oprelay.call("list_projects", {});
// [{ project_key: "myproject" }, { project_key: "ikeo-ops" }]