Tools Reference

Buddhi AI exposes four MCP tools. Each executes under the agent's acting user identity with full policy enforcement.

recall

Scope-filtered semantic search. Returns memories your role is cleared for, each with a citation.

Parameters

Response

{
  "ok": true,
  "denied": false,
  "results": [
    {
      "memory_id": "uuid",
      "title": "API Rate Limiting Policy",
      "content": "All external API endpoints must implement rate limiting...",
      "scope": "engineering",
      "score": 0.89,
      "citation": {
        "source": "GitHub",
        "source_url": "https://github.com/org/repo/pull/123",
        "author": "John Doe",
        "timestamp": "2025-01-15T10:30:00Z"
      }
    }
  ],
  "audit_id": "uuid"
}

Denial Response

If your role isn't cleared:

{
  "ok": true,
  "denied": true,
  "reason": "No memories cleared for your role within scopes [engineering]. Content may exist in scopes you are not cleared for.",
  "allowed_scopes": ["public-docs"],
  "audit_id": "uuid"
}

---

remember

Store a memory in Buddhi AI. Only writes into scopes you're cleared for.

Parameters

Response

{
  "ok": true,
  "memory_id": "uuid",
  "scope": "engineering",
  "conflict_candidates": [
    {
      "memory_id": "existing-uuid",
      "score": 0.82
    }
  ]
}

Denial Response

If you try to write into a scope you can't read:

{
  "ok": false,
  "denied": true,
  "reason": "Your role (IC) is not cleared for scope \"finance\". Allowed: [engineering, public-docs]."
}

---

list_memories

List recent memories visible to your role.

Parameters

Response

{
  "ok": true,
  "memories": [
    {
      "memory_id": "uuid",
      "title": "API Rate Limiting Policy",
      "scope": "engineering",
      "source": "GitHub",
      "author": "John Doe",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

---

get_fact

Fetch a deterministic company fact from the Facts Registry. Returns the authoritative value with citation — never a vector guess.

Parameters

Response

{
  "ok": true,
  "fact": {
    "key": "mrr",
    "label": "Monthly Recurring Revenue",
    "value": "$2.4M",
    "unit": "USD",
    "source_url": "https://dashboard.company.com/mrr",
    "as_of": "2025-01-15T00:00:00Z"
  }
}